Documentation
Documentation
https://docs.okcapsule.app/docs/
APIReference
https://api2-docs.okcapsule.app/
GettingStarted
https://docs.okcapsule.app/docs/getting-started
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/ok-capsule-orders-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
description: '## Overview
The OK Capsule API enables you to programmatically create supplement orders, manage consumers, and track shipments. It is a REST API that accepts JSON requests, returns JSON responses, and uses standard HTTP methods and status codes.
**All requests must be made over HTTPS.**
📚 **Additional Resources:** [Getting Started Guide](https://docs.okcapsule.app/docs/getting-started) | [Recipes & Examples](https://docs.okcapsule.app/docs/category/recipes)
## Getting Started
> **New to OK Capsule API?** Account and brand setup must be completed before contacting OK Capsule about API credentials. If you have not set up your account and brand yet, start with the [Getting Started Guide](https://docs.okcapsule.app/docs/getting-started) before proceeding.
1. **Set up your account** - Your OK Capsule account must be created and active
2. **Set up your brand** - At least one Product Line must be configured in your account
3. **Contact OK Capsule about API credentials** - Reach out to your OK Capsule representative once account and brand setup are complete
4. **Authenticate** - POST to `/v2/authentication/token` to get an access token
5. **List products** - GET `/v2/products` to see available supplements
6. **Create an order** - POST to `/v2/orders` with consumer and product details
7. **Track fulfillment** - Monitor order status and shipping via `/v2/orders` and `/v2/fulfillments`
## Environments
| Environment | Purpose | Notes |
|-------------|---------|-------|
| **Production** | Live orders | Real fulfillment and shipping |
| **Stage** | Testing | Test data only, no real shipments |
⚠️ Users and data are environment-specific. Stage credentials do not work in Production.
## Core Concepts
| Term | Route | Description |
|------|-------|-------------|
| **Client** | `/v2/clients` | Your organization (business partner submitting orders) |
| **Consumer** | `/v2/consumers` | Your end customer who receives supplements |
| **Product** | `/v2/products` | A client-specific instance of an OKC Product with custom branding |
| **Order** | `/v2/orders` | A request to fulfill supplements for a consumer |
| **Order Line** | — | A set of pouches within an order (e.g., 30-day supply) |
| **Pouch** | — | An individual daily packet of supplements |
| **Fulfillment** | `/v2/fulfillments` | Shipping, tracking, and delivery information for an order |
| **Assembly** | `/v2/assemblies` | A client''s predefined bundle of products (commonly called a "pack") |
| **Product Line** | `/v2/product-lines` | A client''s marketing brand (appears on packaging) |
| **OKC Product** | — | A supplement in the OK Capsule master catalog (what OKC purchases from vendors) |
| **User** | `/v2/users` | An authorized person who accesses the API or portal |
| **Contact** | `/v2/contacts` | A person associated with a client, managed for communication purposes |'
version: 2.0.0
title: OKC core API V2 Orders API
contact:
name: Engineering Department, OKCapsule
email: lukas@okcapsule.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- description: Production environment
url: https://na1-prod.okcapsule.app
- description: Stage/Testing environment
url: https://na1-stage.okcapsule.app
tags:
- name: Orders
description: Routes to manage orders
paths:
/v2/orders:
post:
tags:
- Orders
security:
- bearerAuth:
- orders/write
summary: Creates an order.
operationId: createOrder
description: Creates an order. Please note that pouches cannot contain more than 8 supplements per time of administration.
parameters:
- in: query
name: q
description: For internal users only. Use Query DSL *query_string* syntax to send client id.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- consumer
- shipping_address
- order_lines
properties:
consumer:
type: object
description: Consumer info - provide either 'id' for existing consumer, or 'first_name'/'last_name' to create/update
properties:
id:
type: string
format: uuid
description: Existing consumer ID (if provided, first_name/last_name are optional)
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
first_name:
type: string
maxLength: 100
description: Consumer first name (required if no id provided)
example: John
last_name:
type: string
maxLength: 100
description: Consumer last name (required if first_name provided)
example: Doe
email:
type: string
format: email
maxLength: 100
example: john.doe@example.com
phone_number:
type:
- string
- 'null'
maxLength: 15
example: '+12133734253'
shipping_address:
type: object
required:
- address1
- city
- country_name
properties:
addressee:
type:
- string
- 'null'
maxLength: 200
description: Name on shipping label (defaults to consumer name)
example: John Doe
address1:
type: string
maxLength: 100
description: Street address line 1
example: 742 Evergreen Terrace
address2:
type:
- string
- 'null'
maxLength: 100
example: Apt 2B
city:
type: string
maxLength: 50
example: Springfield
province_name:
type:
- string
- 'null'
example: Illinois
country_name:
type: string
example: United States
postal_code:
type:
- string
- 'null'
example: '62701'
order_lines:
type: array
description: Order lines - each represents a pack/pouch configuration
items:
type: object
required:
- pouches
properties:
name:
type:
- string
- 'null'
description: Order line name
example: Monthly Wellness Pack
physician_name:
type:
- string
- 'null'
maxLength: 30
example: Dr. Smith
custom_text_1:
type:
- string
- 'null'
description: Custom text field 1
custom_text_2:
type:
- string
- 'null'
description: Custom text field 2
custom_text_3:
type:
- string
- 'null'
description: Custom text field 3
duration:
type: integer
minimum: 1
maximum: 60
default: 30
description: Duration in days
example: 30
client_custom_order_line_id:
type:
- string
- 'null'
description: Client's custom identifier for this order line
example: LINE-12345
client_custom_line_ids:
type:
- string
- 'null'
description: Client's custom line IDs (comma-separated)
client_custom_pack_name:
type:
- string
- 'null'
description: Custom pack name
example: My Daily Pack
has_special_handling:
type: boolean
default: false
description: Requires special handling
special_handling_instructions:
type:
- string
- 'null'
description: Special handling instructions
is_expedited:
type: boolean
default: false
description: Expedited shipping requested
is_priority_shipping:
type: boolean
default: false
description: Priority shipping requested
is_priority_production:
type: boolean
default: false
description: Priority production requested
is_static_item:
type: boolean
default: false
description: Marks this order line as a static (non-normalized) item. Used by integrations (e.g. Shopify) to skip pack/protocol expansion.
contains_standalone:
type: boolean
default: false
description: Indicates the order line contains a standalone product.
set_id:
type:
- string
- 'null'
format: uuid
description: Client product ID of the SET product this order line was generated from during set explosion.
x-internal: true
status:
type:
- string
- 'null'
description: Order line status. Defaults to the order status if not provided.
example: Pending
order_acceptance_date:
type:
- string
- 'null'
format: date
description: Date the order line was accepted for production.
example: '2026-04-02'
x-internal: true
packaging_asset_group_id:
type:
- string
- 'null'
format: uuid
description: Custom packaging assets
share_url:
type:
- string
- 'null'
description: URL to share this order line
source_line_item_ids:
type:
- array
- 'null'
description: Source line item IDs from external system
items:
oneOf:
- type: string
- type: number
kit_id:
type:
- string
- 'null'
description: Kit identifier
crm_id:
type:
- string
- 'null'
description: CRM identifier
x-internal: true
pouches:
type: array
description: Pouches in this order line
items:
type: object
properties:
pack_id:
type: string
format: uuid
description: Use existing pack/assembly (mutually exclusive with contents)
time_of_administration:
type: string
description: When to take (Morning, Midday, Evening)
example: Morning
custom_label:
type: string
maxLength: 30
pattern: ^[a-zA-Z0-9\s!?@#$%^&*()_\-+\[\]{}':;~/|.,]*$
description: Custom pouch label
example: AM Vitamins
cycle:
type: string
default: daily
example: daily
cycle_length:
type: integer
enum:
- 0
- 7
- 10
default: 7
example: 7
duration:
type:
- integer
- 'null'
minimum: 1
maximum: 60
description: Override duration for this pouch
protocol_id:
type:
- string
- 'null'
format: uuid
description: Protocol to apply
set_id:
type:
- string
- 'null'
format: uuid
description: Client product ID of a SET product. When provided, the set will be automatically exploded into individual order lines during processing. Used primarily by the Shopify integration.
crm_id:
type:
- string
- 'null'
x-internal: true
contents:
type: array
description: Pouch contents (required if pack_id not provided)
items:
type: object
required:
- client_product_id
properties:
client_product_id:
type: string
format: uuid
example: d290f1ee-6c54-4b01-90e6-d701748f0851
serving_size:
type: integer
minimum: 1
example: 2
source:
type: string
default: v2 API
description: Order source
example: Shopify
source_client_order_id:
type:
- string
- 'null'
description: Client's order ID from source system
example: ORD-2024-001
client_custom_order_id:
type:
- string
- 'null'
description: Client's custom order ID
example: CUSTOM-001
order_type:
type: string
enum:
- DTC
- Bulk
default: DTC
description: Order type
email:
type:
- string
- 'null'
format: email
maxLength: 100
description: Contact email for order
phone_number:
type:
- string
- 'null'
description: Contact phone for order
note:
type:
- string
- 'null'
description: Order notes
example: Please include gift message
comments:
type:
- string
- 'null'
description: Comments visible to client
engineering_notes:
type:
- string
- 'null'
description: Internal engineering notes
pack_builder_id:
type:
- string
- 'null'
format: uuid
description: Pack builder used for this order
okc_affiliate_id:
type:
- string
- 'null'
description: Affiliate identifier
example: AFF-12345
crm_id:
type:
- string
- 'null'
x-internal: true
description: CRM identifier (internal only)
status:
type: string
x-internal: true
description: Order status (internal only - defaults to Pending)
state:
type: string
x-internal: true
description: Order state (internal only - defaults to New)
billing_status:
type:
- string
- 'null'
x-internal: true
description: Billing status (internal only)
total:
type: number
x-internal: true
description: Order total (internal only)
discount_total:
type: number
default: 0
x-internal: true
description: Discount total (internal only)
fulfillment_fee_total:
type: number
default: 0
x-internal: true
description: Fulfillment fee total (internal only)
shipping_fee_total:
type: number
default: 0
x-internal: true
description: Shipping fee total (internal only)
example:
consumer:
first_name: John
last_name: Doe
email: john.doe@example.com
shipping_address:
address1: 742 Evergreen Terrace
city: Springfield
province_name: Illinois
country_name: United States
postal_code: '62701'
order_lines:
- duration: 30
pouches:
- time_of_administration: Morning
contents:
- client_product_id: d290f1ee-6c54-4b01-90e6-d701748f0851
serving_size: 2
x-examples:
required-only:
summary: Order with required fields only
value:
consumer:
first_name: John
last_name: Doe
shipping_address:
address1: 742 Evergreen Terrace
city: Springfield
country_name: United States
order_lines:
- pouches:
- contents:
- client_product_id: d290f1ee-6c54-4b01-90e6-d701748f0851
with-existing-consumer:
summary: Order with existing consumer ID
value:
consumer:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
shipping_address:
address1: 742 Evergreen Terrace
city: Springfield
country_name: United States
order_lines:
- pouches:
- contents:
- client_product_id: d290f1ee-6c54-4b01-90e6-d701748f0851
with-pack-id:
summary: Order using existing pack/assembly
value:
consumer:
first_name: John
last_name: Doe
shipping_address:
address1: 742 Evergreen Terrace
city: Springfield
country_name: United States
order_lines:
- pouches:
- pack_id: f1e2d3c4-b5a6-7890-1234-567890abcdef
time_of_administration: Morning
complete:
summary: Order with all optional fields
value:
consumer:
first_name: John
last_name: Doe
email: john.doe@example.com
phone_number: '+12133734253'
shipping_address:
addressee: John Doe
address1: 742 Evergreen Terrace
address2: Apt 2B
city: Springfield
province_name: Illinois
country_name: United States
postal_code: '62701'
order_lines:
- name: Monthly Wellness Pack
physician_name: Dr. Smith
custom_text_1: Custom text 1
custom_text_2: Custom text 2
custom_text_3: Custom text 3
duration: 30
client_custom_order_line_id: LINE-12345
client_custom_pack_name: My Daily Pack
has_special_handling: false
is_expedited: false
is_priority_shipping: false
is_priority_production: false
pouches:
- time_of_administration: Morning
custom_label: AM Vitamins
cycle: daily
cycle_length: 7
contents:
- client_product_id: d290f1ee-6c54-4b01-90e6-d701748f0851
serving_size: 2
- client_product_id: e2f3a4b5-c6d7-8901-2345-678901bcdef0
serving_size: 1
- time_of_administration: Evening
custom_label: PM Vitamins
cycle: daily
cycle_length: 7
contents:
- client_product_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
serving_size: 1
source: Shopify
source_client_order_id: ORD-2024-001
client_custom_order_id: CUSTOM-001
order_type: DTC
email: john.doe@example.com
phone_number: '+12133734253'
note: Please include gift message
comments: First order from new customer
okc_affiliate_id: AFF-12345
examples:
OrderFullExample:
$ref: '#/components/examples/OrderFullSample'
OrderRequiredWithConsumerIdExample:
$ref: '#/components/examples/OrderRequiredWithConsumerIdSample'
OrderWithConsumerFieldsExample:
$ref: '#/components/examples/OrderWithConsumerFieldsSample'
OrderWithAssemblyExample:
$ref: '#/components/examples/OrderWithAssemblySample'
OrderWithMultipleTOAsExample:
$ref: '#/components/examples/OrderWithMultipleTOAsSample'
OrderWithMultipleOrderLinesExample:
$ref: '#/components/examples/OrderWithMultipleOrderLinesSample'
OrderWithProductsAndPackExample:
$ref: '#/components/examples/OrderWithProductsAndPackSample'
responses:
'201':
description: Returns a created Order object.
content:
application/json:
schema:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
'422':
$ref: '#/components/responses/422ValidationError'
default:
$ref: '#/components/responses/UnknownError'
get:
tags:
- Orders
security:
- bearerAuth:
- orders/read
summary: List all orders
operationId: listOrders
description: "List all orders.\n\n Filterable fields:\n * name\n * status\n * state\n * source\n * billing_status\n * submission_date\n * crm_id\n"
parameters:
- $ref: '#/components/parameters/LimitParameters'
- $ref: '#/components/parameters/CursorParameters'
- $ref: '#/components/parameters/SortByParameters'
- $ref: '#/components/parameters/QueryParameters'
responses:
'200':
description: Search results matching criteria
content:
application/json:
schema:
required:
- orders
properties:
orders:
type: array
items:
$ref: '#/components/schemas/Order'
default:
$ref: '#/components/responses/UnknownError'
/v2/orders/count:
get:
tags:
- Orders
security:
- bearerAuth:
- orders/read
summary: Count of all orders
operationId: getOrderTotalCount
description: "Count of all orders.\n\nFilterable fields:\n * name\n * status\n * state\n * source\n * billing_status\n * submission_date\n * crm_id\n"
parameters:
- $ref: '#/components/parameters/QueryParameters'
responses:
'200':
description: Search results matching criteria
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/Count'
default:
$ref: '#/components/responses/UnknownError'
/v2/orders/by-client-order-id/{clientCustomOrderId}:
get:
tags:
- Orders
security:
- bearerAuth:
- orders/read
summary: Retrieve an order by client custom order ID
operationId: getOrderByClientCustomId
description: Retrieve an order using the client's custom order identifier (`client_custom_order_id`) instead of the internal order UUID. The order must belong to the authenticated client.
parameters:
- name: clientCustomOrderId
in: path
required: true
description: The client's custom order identifier.
schema:
type: string
responses:
'200':
description: Returns the Order object matching the given client custom order ID.
content:
application/json:
schema:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: No order found with the given client custom order ID.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error response.
/v2/orders/{id}:
get:
tags:
- Orders
security:
- bearerAuth:
- orders/read
summary: Retrieve an order
operationId: getOrder
description: Retrieve an order.
parameters:
- $ref: '#/components/parameters/IdParameter'
- in: query
name: q
description: For internal users only. Use Query DSL *query_string* syntax to send client id.
schema:
type: string
responses:
'200':
description: Returns the Order object for a valid identifier.
content:
application/json:
schema:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error response.
put:
tags:
- Orders
security:
- bearerAuth:
- orders/write
summary: Update an order.
operationId: updateOrder
description: Update an order.
parameters:
- $ref: '#/components/parameters/IdParameter'
- in: query
name: q
description: For internal users only. Use Query DSL *query_string* syntax to send client id.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
description: 'All fields are optional for updates. Include ''is_deleted: true'' on nested objects to delete them.'
properties:
consumer:
type: object
description: Consumer info - provide 'id' for existing or 'first_name'/'last_name' to update
properties:
id:
type: string
format: uuid
description: Consumer ID
first_name:
type: string
maxLength: 100
example: John
last_name:
type: string
maxLength: 100
example: Doe
email:
type: string
format: email
maxLength: 100
shipping_address:
type: object
properties:
addressee:
type:
- string
- 'null'
maxLength: 200
address1:
type: string
maxLength: 100
address2:
type:
- string
- 'null'
maxLength: 100
city:
type: string
maxLength: 50
province_name:
type:
- string
- 'null'
co
# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ok-capsule/refs/heads/main/openapi/ok-capsule-orders-api-openapi.yml