Create Orders

This guide covers common order creation patterns.

Full API Reference

Response examples are simplified. See the complete endpoint documentation for the full response schema.

Minimal Order Example

The absolute minimum order payload:

{
  "consumer": {
    "first_name": "John",
    "last_name": "Doe"
  },
  "shipping_address": {
    "address1": "123 Main St",
    "city": "Springfield",
    "country_name": "United States"
  },
  "order_lines": [
    {
      "pouches": [
        {
          "contents": [{ "client_product_id": "YOUR-PRODUCT-UUID-HERE" }]
        }
      ]
    }
  ]
}

Get Your Product ID First

Before creating an order, list your products to get valid IDs:

curl -X GET https://na1-prod.okcapsule.app/v2/products \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Use an id from the response in client_product_id.

Required Fields

Every order requires:

consumer - Who receives the order (new or existing)
shipping_address - Where to ship
order_lines - What to include (pouches with contents)

Consumer: ID or name, never both

The consumer object must contain either an id (existing consumer) or both first_name and last_name (new consumer). Mixing the two — for example, passing id together with first_name — is rejected.

Order Line Types

Each order_line is one of three types. The shape of the order line (and its pouches) tells the API which type you're sending — there is no type field.

Custom Pack

Client defines which supplements go into each pouch. Requires pouches[] with contents[]. Must not include standalone_id.

{
  "order_lines": [
    {
      "duration": 30,
      "pouches": [
        {
          "time_of_administration": "Morning",
          "contents": [
            { "client_product_id": "vitamin-d3-uuid", "serving_size": 2 },
            { "client_product_id": "magnesium-uuid", "serving_size": 1 }
          ]
        }
      ]
    }
  ]
}

Curated Pack

A pouch sourced from a pre-defined assembly instead of inline ingredients. The pouch references pack_id and omits contents. The order line still uses pouches[] (see Example 3 for the full example).

{
  "order_lines": [
    {
      "pouches": [
        {
          "pack_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
          "time_of_administration": "Morning"
        }
      ]
    }
  ]
}

tip

A pouch must specify either pack_id or contents, not both.

Standalone

A single non-pouched product (e.g. a bottle or a single SKU). Requires standalone_id and quantity (integer ≥ 1). Must not include pouches.

{
  "order_lines": [
    {
      "standalone_id": "a9b8c7d6-e5f4-3210-9876-543210fedcba",
      "quantity": 2
    }
  ]
}

A single order can mix types — include one order line per pack or standalone product.

Example 1: New Consumer

Create an order for a new consumer by providing their details inline:

TypeScript
JSON Payload

const order = {
  consumer: {
    first_name: "John",
    last_name: "Doe",
    email: "john.doe@example.com",
    phone_number: "+12133734253",
  },
  shipping_address: {
    address1: "742 Evergreen Terrace",
    city: "Springfield",
    province_name: "Illinois",
    country_name: "United States",
    postal_code: "62701",
  },
  order_lines: [
    {
      pouches: [
        {
          time_of_administration: "Morning",
          contents: [
            {
              client_product_id: "d290f1ee-6c54-4b01-90e6-d701748f0851",
              serving_size: 2,
            },
          ],
        },
      ],
    },
  ],
};

const response = await fetch("https://na1-prod.okcapsule.app/v2/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(order),
});

const { order: created } = await response.json();

{
  "consumer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+12133734253"
  },
  "shipping_address": {
    "address1": "742 Evergreen Terrace",
    "city": "Springfield",
    "province_name": "Illinois",
    "country_name": "United States",
    "postal_code": "62701"
  },
  "order_lines": [
    {
      "pouches": [
        {
          "time_of_administration": "Morning",
          "contents": [
            {
              "client_product_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
              "serving_size": 2
            }
          ]
        }
      ]
    }
  ]
}

The consumer will be created automatically and the ID returned in the response.

Example 2: Existing Consumer

Reference an existing consumer by ID:

TypeScript
JSON Payload

const order = {
  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" },
          ],
        },
      ],
    },
  ],
};

const response = await fetch("https://na1-prod.okcapsule.app/v2/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(order),
});

{
  "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" }
          ]
        }
      ]
    }
  ]
}

Example 3: Using an Assembly (Pre-built Pack)

Use a pre-configured assembly instead of specifying contents:

TypeScript
JSON Payload

const order = {
  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",
        },
      ],
    },
  ],
};

{
  "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"
        }
      ]
    }
  ]
}

tip

When using pack_id, you cannot also specify contents. Choose one or the other.

Example 4: Multiple Times of Administration

Create pouches for different times of day:

TypeScript
JSON Payload

const order = {
  consumer: {
    first_name: "John",
    last_name: "Doe",
  },
  shipping_address: {
    address1: "742 Evergreen Terrace",
    city: "Springfield",
    country_name: "United States",
  },
  order_lines: [
    {
      duration: 30,
      pouches: [
        {
          time_of_administration: "Morning",
          custom_label: "AM Vitamins",
          contents: [
            { client_product_id: "product-1-uuid", serving_size: 2 },
            { client_product_id: "product-2-uuid", serving_size: 1 },
          ],
        },
        {
          time_of_administration: "Evening",
          custom_label: "PM Vitamins",
          contents: [{ client_product_id: "product-3-uuid", serving_size: 1 }],
        },
      ],
    },
  ],
};

{
  "consumer": {
    "first_name": "John",
    "last_name": "Doe"
  },
  "shipping_address": {
    "address1": "742 Evergreen Terrace",
    "city": "Springfield",
    "country_name": "United States"
  },
  "order_lines": [
    {
      "duration": 30,
      "pouches": [
        {
          "time_of_administration": "Morning",
          "custom_label": "AM Vitamins",
          "contents": [
            { "client_product_id": "product-1-uuid", "serving_size": 2 },
            { "client_product_id": "product-2-uuid", "serving_size": 1 }
          ]
        },
        {
          "time_of_administration": "Evening",
          "custom_label": "PM Vitamins",
          "contents": [
            { "client_product_id": "product-3-uuid", "serving_size": 1 }
          ]
        }
      ]
    }
  ]
}

Example 5: Common Optional Fields

JSON Payload

{
  "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"
  },
  "source": "Shopify",
  "source_client_order_id": "ORD-2024-001",
  "order_type": "DTC",
  "order_lines": [
    {
      "name": "Monthly Wellness Pack",
      "physician_name": "Dr. Smith",
      "duration": 30,
      "is_expedited": false,
      "pouches": [
        {
          "time_of_administration": "Morning",
          "custom_label": "AM Vitamins",
          "cycle": "daily",
          "cycle_length": 7,
          "contents": [
            { "client_product_id": "product-1-uuid", "serving_size": 2 },
            { "client_product_id": "product-2-uuid", "serving_size": 1 }
          ]
        }
      ]
    }
  ]
}

Field Constraints

Field	Max Length	Notes
`consumer.first_name`	100
`consumer.last_name`	100
`consumer.email`	100
`consumer.phone_number`	30	Typically an E.164 number (`+12133734253`). Extensions are accepted (`+12107284548ext12733`). Formatted numbers like `(213) 373-4253` are not validated by the API but should be avoided since they aren't normalized before being passed to carriers.
`shipping_address.addressee`	200	Defaults to consumer name
`shipping_address.address1`	100
`shipping_address.address2`	100
`shipping_address.city`	50
`order_line.physician_name`	30
`pouch.custom_label`	30	Alphanumeric + common symbols
`order_line.duration`	1-60	Days. Defaults to `30` when omitted.

Less Common Optional Fields

Field	Level	Default	Notes
`pouch.cycle`	pouch	`"daily"`	Cycle marker for the pouch.
`pouch.cycle_length`	pouch	`7`	Days the cycle repeats. Allowed values: `0`, `7`, `10`.
`order_line.is_priority_shipping`	order_line	`false`	Priority shipping flag (separate from `is_expedited`).
`order_line.is_priority_production`	order_line	`false`	Priority production flag.
`order_line.lot_information`	order_line	`null`	Free-text traceability string.

Validation Rules

Pouch Limits

Maximum 8 supplements per pouch
Orders are rejected if pouch count exceeds dispenser box capacity

Time of Administration

Common values: Morning, Midday, Evening. The API accepts other values, but only these three are supported across the rest of the platform — contact your OKC representative before using anything else.

Error Handling

Common validation errors:

Error	Cause
`consumer.last_name is required`	Providing `first_name` requires `last_name`
`Either pack_id or contents required`	Pouch needs one or the other
`Invalid client_product_id`	Product doesn't exist or isn't active

Create Orders

Minimal Order Example​

Required Fields​

Order Line Types​

Custom Pack​

Curated Pack​

Standalone​

Example 1: New Consumer​

Example 2: Existing Consumer​

Example 3: Using an Assembly (Pre-built Pack)​

Example 4: Multiple Times of Administration​

Example 5: Common Optional Fields​

Field Constraints​

Less Common Optional Fields​

Validation Rules​

Error Handling​

See Also​