Skip to main content

Manage Consumers

Consumers are the end customers who receive supplement orders.

Full API Reference

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

Create a Consumer​

const consumer = {
  email: "john.doe@example.com",
  first_name: "John",
  last_name: "Doe",
  phone_number: "+12133734253",
  client_custom_consumer_id: "CUST-12345",
};

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

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

Response:

{
  "consumer": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+12133734253",
    "client_custom_consumer_id": "CUST-12345",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Required Fields​

FieldMax Length
email100
first_name100
last_name100

Optional Fields​

FieldMax LengthNotes
phone_number15E.164 format recommended
client_custom_consumer_id-Your internal customer ID

Get a Consumer​

const response = await fetch(
  `https://na1-prod.okcapsule.app/v2/consumers/${consumerId}`,
  {
    headers: { Authorization: `Bearer ${access_token}` },
  }
);

const { consumer } = await response.json();

List Consumers​

const response = await fetch(
  "https://na1-prod.okcapsule.app/v2/consumers?limit=20",
  {
    headers: { Authorization: `Bearer ${access_token}` },
  }
);

const { consumers } = await response.json();

Query Parameters​

ParameterDescription
limitNumber of results (default: 20, max: 100)
cursorPagination cursor for next page

Update a Consumer​

const response = await fetch(
  `https://na1-prod.okcapsule.app/v2/consumers/${consumerId}`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${access_token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      first_name: "Jonathan",
      phone_number: "+12135551234",
    }),
  }
);

const { consumer } = await response.json();

Only include fields you want to update.

Consumer Addresses​

Consumers can have multiple addresses.

Add an Address​

const address = {
  is_default: true,
  address_type: "shipping",
  addressed_to: "John Doe",
  address1: "742 Evergreen Terrace",
  address2: "Apt 2B",
  city: "Springfield",
  province_name: "Illinois",
  country_name: "United States",
  postal_code: "62701",
  phone_number: "+12175551234",
};

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

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

Address Field Constraints​

FieldMax Length
addressed_to35
address1100
address2100
city50
province_name30
postal_code10
phone_number15

Address Types​

  • shipping - Delivery address
  • billing - Billing address
  • return - Return address (requires phone number)

List Consumer Addresses​

GET /v2/consumers/{consumerId}/addresses

Update an Address​

PUT /v2/consumers/{consumerId}/addresses/{addressId}

Inline Consumer Creation​

When creating orders, you can create consumers inline:

{
  "consumer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "shipping_address": { ... },
  "order_lines": [ ... ]
}

The consumer is created automatically if no matching email exists.

Best Practices​

Use client_custom_consumer_id

Store your internal customer ID in client_custom_consumer_id to easily correlate consumers between systems.

See Also​