Skip to main content

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)

Pattern 1: New Consumer​

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

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();

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

Pattern 2: Existing Consumer​

Reference an existing consumer by ID:

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),
});

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

Use a pre-configured assembly instead of specifying contents:

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",
        },
      ],
    },
  ],
};
tip

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

Pattern 4: Multiple Times of Administration​

Create pouches for different times of day:

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 }],
        },
      ],
    },
  ],
};

Pattern 5: Complete Order with All Options​

{
  "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​

FieldMax LengthNotes
consumer.first_name100
consumer.last_name100
consumer.email100
consumer.phone_number15E.164 format
shipping_address.addressee200Defaults to consumer name
shipping_address.address1100
shipping_address.address2100
shipping_address.city50
order_line.physician_name30
pouch.custom_label30Alphanumeric + common symbols
order_line.duration1-60Days

Validation Rules​

Pouch Limits
  • Maximum 8 supplements per pouch
  • Orders are rejected if pouch count exceeds dispenser box capacity
Time of Administration

Valid values: Morning, Midday, Evening

Error Handling​

Common validation errors:

ErrorCause
consumer.last_name is requiredProviding first_name requires last_name
Either pack_id or contents requiredPouch needs one or the other
Invalid client_product_idProduct doesn't exist or isn't active

See Also​