The Integrations Orders API from OK Capsule — 2 operation(s) for integrations orders.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/ok-capsule-integrations-orders-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
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 Integrations 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: Integrations Orders
paths:
/v2/integrations/orders:
post:
tags:
- Integrations Orders
summary: Creates an order.
operationId: createIntegrationOrder
description: Creates an order.
parameters:
- $ref: '#/components/parameters/HmacParameter'
- in: query
name: client_id
required: true
schema:
type: string
minimum: 1
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'
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'
/v2/integrations/orders/{id}:
put:
tags:
- Integrations Orders
summary: Update an order.
operationId: updateIntegrationOrder
description: Update an order.
parameters:
- $ref: '#/components/parameters/HmacParameter'
- $ref: '#/components/parameters/IdParameter'
- in: query
name: client_id
required: true
schema:
type: string
minimum: 1
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'
country_name:
type: string
postal_code:
type:
- string
- 'null'
order_lines:
type: array
description: Order lines - include 'id' to update existing, omit to add new
items:
type: object
properties:
id:
type: string
format: uuid
description: Order line ID (required for updates)
is_deleted:
type: boolean
description: Set to true to delete this order line
fulfillment_id:
type: string
format: uuid
description: Associated fulfillment ID
name:
type:
- string
- 'null'
physician_name:
type:
- string
- 'null'
maxLength: 30
custom_text_1:
type:
- string
- 'null'
custom_text_2:
type:
- string
- 'null'
custom_text_3:
type:
- string
- 'null'
duration:
type: integer
minimum: 1
maximum: 60
client_custom_order_line_id:
type:
- string
- 'null'
client_custom_line_ids:
type:
- string
- 'null'
client_custom_pack_name:
type:
- string
- 'null'
has_special_handling:
type: boolean
special_handling_instructions:
type:
- string
- 'null'
is_expedited:
type: boolean
is_priority_shipping:
type: boolean
is_priority_production:
type: boolean
contains_standalone:
type: boolean
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
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
kit_id:
type:
- string
- 'null'
crm_id:
type:
- string
- 'null'
x-internal: true
source_line_item_ids:
type:
- array
- 'null'
items:
oneOf:
- type: string
- type: number
pouches:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ok-capsule/refs/heads/main/openapi/ok-capsule-integrations-orders-api-openapi.yml