Orders

Read and manage orders created by checkout. Authenticated customers get their own orders; guests can access individual orders by passing the order’s `bill_token` as a query parameter.

GET /api/v1/orders

List orders for the authenticated customer. Supports status, limit, offset, and location_id filters. Requires a customer session.

Request

cURL

curl "https://api.cimplify.io/api/v1/orders?status=confirmed&limit=20" \
  -H "X-Public-Key: pk_test_your_publishable_key"

Response

{
  "success": true,
  "data": [
    {
      "id": "ord_01H…",
      "order_number": "ORD-1284",
      "status": "confirmed",
      "order_type": "delivery",
      "items": [
        {
          "product_id": "prod_abc123",
          "product_name": "Espresso",
          "variant_name": "Double",
          "quantity": 2,
          "unit_price": "6.00",
          "total": "12.00"
        }
      ],
      "subtotal": "12.00",
      "tax_amount": "1.06",
      "total_price": "13.06",
      "currency": "GHS",
      "customer_name": "Ama Mensah",
      "created_at": "2026-05-07T16:42:18Z"
    }
  ]
}

Fetch one order. Authenticated customers are matched against the order’s customer_id; guests must pass the token query parameter (the bill_token from the checkout response). On a mismatch the server returns 404 NOT_FOUND (never 403) to avoid leaking order existence.

Request (guest)

cURL

curl "https://api.cimplify.io/api/v1/orders/ord_01H…?token=bt_n3k…" \
  -H "X-Public-Key: pk_test_your_publishable_key"

Request (authenticated)

cURL

curl https://api.cimplify.io/api/v1/orders/ord_01H… \
  -H "X-Public-Key: pk_test_your_publishable_key"

GET /api/v1/orders/{order_id}/payment-status

Poll the live payment status for an order. Same access rules as GET /orders/:id; guests must include ?token=….

cURL

curl "https://api.cimplify.io/api/v1/orders/ord_01H…/payment-status?token=bt_n3k…" \
  -H "X-Public-Key: pk_test_your_publishable_key"

Response

{
  "success": true,
  "data": {
    "order_id": "ord_01H…",
    "payment_status": "succeeded",
    "payment_reference": "ref_kjz…",
    "amount": "13.06",
    "currency": "GHS",
    "settled_at": "2026-05-07T16:43:02Z"
  }
}

POST /api/v1/orders/{order_id}/cancel

Cancel an order. Honours Idempotency-Key. Optional reason body (max 500 chars). Guests must include ?token=….

cURL

curl -X POST "https://api.cimplify.io/api/v1/orders/ord_01H…/cancel?token=bt_n3k…" \
  -H "X-Public-Key: pk_test_your_publishable_key" \
  -H "Idempotency-Key: 5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1" \
  -H "Content-Type: application/json" \
  -d '{"reason": "ordered the wrong item"}'

POST /api/v1/orders/{order_id}/customer

Attach an authenticated customer to a previously-guest order. Useful for “guest-to-account” flows where the visitor signs up after checkout. Body: { customer_id }.

cURL

curl -X POST "https://api.cimplify.io/api/v1/orders/ord_01H…/customer?token=bt_n3k…" \
  -H "X-Public-Key: pk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "cus_01H…"}'

POST /api/v1/orders/{order_id}/verify-payment

Re-verify the payment with the underlying provider, e.g. after a redirect-flow handoff. Returns the canonical payment status.

cURL

curl -X POST "https://api.cimplify.io/api/v1/orders/ord_01H…/verify-payment?token=bt_n3k…" \
  -H "X-Public-Key: pk_test_your_publishable_key"

Order statuses

Status	Description
`pending`	Awaiting confirmation / payment to settle.
`confirmed`	Confirmed by the business.
`preparing`	In the kitchen / fulfilment queue.
`ready`	Ready for pickup or out for delivery.
`completed`	Fulfilled.
`cancelled`	Cancelled by customer or business.

Checkout Where orders, and the bill_token, come from.
Webhooks React to order lifecycle events server-side.

Orders

On this page