Order Lifecycle

Managing orders after creation.

Full API Reference

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

Key Concepts

Edit Window

Orders can only be modified while in Pending or On Hold status. Once an order moves to Accepted, it cannot be modified.

Nightly Processing

Orders in Pending status are processed and moved to Accepted during the nightly batch at midnight PST.

Production Cutoff

Once an order enters In Production status, it cannot be canceled.

Order Statuses

Status	Description	Can Edit?	Can Cancel?
Pending	Order received, awaiting nightly batch	✅ Yes	✅ Yes
On Hold	Paused for review	✅ Yes	✅ Yes
Accepted	Validated and queued for production	❌ No	⚠️ Contact support
In Production	Being manufactured	❌ No	❌ No
Shipped	Handed to carrier, tracking available	❌ No	❌ No
Delivered	Confirmed delivery	❌ No	❌ No
Canceled by Client	You requested cancellation	—	—
Canceled by OKC	OK Capsule canceled the order	—	—

What You Can Update

Orders in Pending or On Hold status can be updated:

Field	Updatable?	Notes
shipping_address	✅ Yes	Full address can be changed
consumer	✅ Yes	Can change or reassign consumer
order_lines	✅ Yes	Can modify products, pouches, quantities
email	✅ Yes
phone_number	✅ Yes
note	✅ Yes
status	✅ Limited	Only to Pending, On Hold, or Canceled by Client

Read-only fields (cannot be changed by clients):

• total, discount_total, fulfillment_fee_total, shipping_fee_total
• state, submission_date, source, crm_id

On Hold

Updating an order may trigger On Hold status if the changes require review (e.g., address validation issues).

Check Order Status

TypeScript

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

const { order } = await response.json();
console.log(order.status); // "Pending", "Accepted", "Shipped", etc.

cURL

curl -X GET "https://na1-prod.okcapsule.app/v2/orders/{orderId}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Update an Order

Update shipping address while order is still Pending or On Hold:

TypeScript

const response = await fetch(
  `https://na1-prod.okcapsule.app/v2/orders/${orderId}`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${access_token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      shipping_address: {
        address1: "123 New Street",
        city: "New City",
        province_name: "California",
        country_name: "United States",
        postal_code: "90210",
      },
    }),
  }
);

if (!response.ok) {
  const error = await response.json();
  // Will fail if order is not in Pending or On Hold status
  console.error("Cannot update:", error.message);
}

cURL

curl -X PUT "https://na1-prod.okcapsule.app/v2/orders/{orderId}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_address": {
      "address1": "123 New Street",
      "city": "New City",
      "province_name": "California",
      "country_name": "United States",
      "postal_code": "90210"
    }
  }'

Cancel an Order

You can cancel orders directly via API while they are in Pending or On Hold status.

Once an order is Accepted or later, cancellation requires contacting OK Capsule support.

TypeScript

// First, check if the order can be canceled via API
const checkResponse = await fetch(
  `https://na1-prod.okcapsule.app/v2/orders/${orderId}`,
  {
    headers: { Authorization: `Bearer ${access_token}` },
  }
);
const { order } = await checkResponse.json();

// Can only self-cancel while Pending or On Hold
const selfCancelableStatuses = ["Pending", "On Hold"];
if (!selfCancelableStatuses.includes(order.status)) {
  console.error(
    `Cannot cancel order in "${order.status}" status via API. Contact support.`
  );
  return;
}

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

if (response.ok) {
  console.log("Order canceled successfully");
} else {
  const error = await response.json();
  console.error("Cannot cancel:", error.message);
}

cURL

curl -X PUT "https://na1-prod.okcapsule.app/v2/orders/{orderId}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "Canceled by Client"}'

List Orders by Status

TypeScript

const params = new URLSearchParams({
  "filter[status]": "Shipped",
  limit: "50",
});

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

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

cURL

curl -X GET "https://na1-prod.okcapsule.app/v2/orders?filter[status]=Shipped&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

When Orders Ship

When an order ships, a fulfillment record is created with tracking information. See Track Fulfillments for details.

Polling for Updates

Poll the orders endpoint periodically to check for status changes:

// Check for shipped orders since last check
const params = new URLSearchParams({
  "filter[status]": "Shipped",
  "filter[updated_at][gte]": lastCheckTime.toISOString(),
});

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

Polling Frequency

Order statuses are typically updated every 6 hours during business operations. Polling more frequently than every few hours is unnecessary and may be rate limited.