Orders

Use the Orders API to import sales from another system, create orders from a custom checkout, track fulfillment, record partial or full payment, schedule future orders, and retrieve receipts.

All endpoints use the /v1/orders prefix and authenticate with an API key. Amounts are expressed in the business currency as decimal numbers, not minor units.

Endpoints

Method	Endpoint	Scope	Purpose
`GET`	`/v1/orders`	`orders:read`	List and filter orders
`GET`	`/v1/orders/:id`	`orders:read`	Retrieve one order
`POST`	`/v1/orders`	`orders:write`	Create an order
`PATCH`	`/v1/orders/:id`	`orders:write`	Update status, payment, customer, or scheduling
`POST`	`/v1/orders/:id/confirm`	`orders:write`	Confirm a scheduled order
`POST`	`/v1/orders/:id/requery`	`orders:read`	Refresh an automated payment
`POST`	`/v1/orders/:id/receipt`	`orders:read`	Generate a receipt URL
`DELETE`	`/v1/orders/:id`	`orders:write`	Delete an order and restore inventory

Order resource

Order reads and successful create, update, confirmation, and payment refresh operations return the same order shape.


{
  "id": "5037c85a-44c6-4c3a-bd7d-3e21e73915e1",
  "shortCode": "482193",
  "status": "pending",
  "paymentStatus": "partial",
  "summary": "2x Jollof Rice",
  "items": [
    {
      "id": "2b783a34-5b8b-43b7-a441-dcb8ae7db843",
      "productId": "7a59174f-3207-42a6-8fab-5b8d8b2929fb",
      "variantId": "f91718fb-1487-4ada-a44c-794b1ba5a3d3",
      "productName": "Jollof Rice",
      "variantName": "Large",
      "quantity": 2,
      "unitPrice": 3500,
      "originalUnitPrice": 4000,
      "discountAmount": 1000,
      "subtotalAmount": 7000,
      "taxAmount": 0,
      "totalPrice": 7000,
      "imageUrl": "https://cdn.example.com/jollof-rice.jpg",
      "modifiers": [
        {
          "modifierGroupId": "4f7f9ff4-19e4-4cbb-b7c6-45275e70fc6f",
          "modifierOptionId": "f494ef42-178a-4e16-bcf2-481a52d55833",
          "name": "Extra chicken",
          "priceDelta": 1000
        }
      ],
      "components": []
    }
  ],
  "totalAmount": 7000,
  "subtotalAmount": 8000,
  "discountAmount": 1000,
  "serviceChargeAmount": 0,
  "amountPaid": 4000,
  "remainingAmount": 3000,
  "currency": "NGN",
  "paymentMethod": "transfer",
  "customer": {
    "id": "3cadb42d-571b-4979-94b4-c094c60820c4",
    "name": "Ada Lovelace",
    "phoneNumber": "+2348012345678",
    "whatsappNumber": "+2348012345678"
  },
  "store": {
    "id": "837ceae4-43c2-4bbb-830c-1099d36b9d05",
    "name": "Lekki"
  },
  "channel": "checkout",
  "channelFulfilledAt": null,
  "isAutomated": false,
  "deposit": null,
  "scheduledFor": null,
  "scheduledConfirmedAt": null,
  "serviceMode": "takeaway",
  "tableSessionId": null,
  "tableLabel": null,
  "kitchenTicketId": null,
  "kitchenTicketStatus": null,
  "recordedBy": {
    "id": "4e3d75bb-4208-4dd4-a292-2c27ecb99185",
    "name": "API integration"
  },
  "servedBy": null,
  "tags": [],
  "notes": "Pack cutlery separately",
  "receiptUrl": null,
  "cancellation": null,
  "occurredAt": "2026-07-14T10:30:00.000Z",
  "date": "2026-07-14T10:30:00.000Z",
  "createdAt": "2026-07-14T10:30:02.000Z",
  "entrySource": "live",
  "recoverySessionId": null,
  "academicTerm": null
}

Status values

Status	Meaning
`scheduled`	Created for future fulfillment and not yet confirmed
`pending`	Created but not fully paid or otherwise awaiting completion
`completed`	Fully paid or explicitly completed
`cancelled`	Cancelled with an optional recorded reason
`refunded`	Previously refunded through a supported refund workflow

paymentStatus is calculated from the order totals:

Payment status	Rule
`pending`	`amountPaid` is zero
`partial`	`amountPaid` is greater than zero and less than `totalAmount`
`paid`	`amountPaid` is equal to or greater than `totalAmount`

Setting an order status to refunded does not move money. The public update endpoint therefore does not accept refunded. Use the applicable payment provider refund workflow, then consume the resulting order or transaction update.

List orders


GET /v1/orders?status=pending,scheduled&channel=whatsapp,voice&limit=25

Query parameters

Comma-separated filters use lowercase values.

Parameter	Type	Description
`status`	enum list	`scheduled`, `pending`, `completed`, `cancelled`, `refunded`
`payment_status`	enum list	`paid`, `partial`, `pending`
`channel`	enum list	Filter by one or more order channels
`service_mode`	enum list	`dine_in`, `takeaway`, `room_service`
`payment_method`	enum	`cash`, `transfer`, `pos`, `cloove_pay`, `credit`, `other`
`customer_id`	uuid	Orders linked to a customer
`store_id`	uuid	Orders for one store, including business-level orders
`store_ids`	uuid list	Comma-separated store IDs
`recorded_by_id`	uuid	Orders created by a user
`staff_id`	uuid	Orders recorded or served by a user
`served_by_user_id`	uuid	Orders assigned to a server or waiter
`table_session_id`	uuid	Orders charged to a restaurant table session
`academic_term_id`	uuid	Orders associated with an academic term
`tag_ids`	uuid list	Orders containing any listed tag
`start_date`	ISO date or timestamp	Orders occurring on or after this value
`end_date`	ISO date or timestamp	Orders occurring on or before this value
`search`	string	Match an order short code or customer name
`is_automated`	boolean	Whether the order has an automated deposit
`channel_fulfilled`	boolean	Whether a channel order has been treated
`scheduled_only`	boolean	Return scheduled orders in fulfillment order
`page`	integer	Page number, default `1`
`limit`	integer	Items per page, default `50`, maximum `100`

Response


{
  "message": "Orders retrieved",
  "data": [],
  "meta": {
    "total": 0,
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "hasMore": false
  },
  "summary": {
    "todayOrders": 4,
    "todayRevenue": 42000,
    "totalOrders": 138,
    "filteredOrders": 12,
    "totalRevenue": 184000,
    "averageOrderValue": 15333.33,
    "pendingOrdersCount": 6,
    "pendingOutstandingAmount": 27000,
    "completedOrdersCount": 7,
    "completedRevenue": 157000,
    "cancelledOrdersCount": 1,
    "cancelledRevenue": 0
  }
}

filteredOrders and the revenue fields respect the supplied filters. totalOrders and pendingOrdersCount are business workload counts and are not reduced by every list filter.

Retrieve an order


GET /v1/orders/5037c85a-44c6-4c3a-bd7d-3e21e73915e1

This endpoint returns the complete order resource, including line items, customer, store, payment, scheduling, restaurant, staff, deposit, and cancellation data.

A missing order, a deleted order, or an order belonging to another business returns:


{
  "error": "not_found",
  "message": "Order not found."
}

Create an order


POST /v1/orders
Idempotency-Key: 90ed7ca0-dd71-4550-8bea-62b99d551d41
Content-Type: application/json

Always use a unique UUID as the Idempotency-Key. Repeating a successful request with the same key returns the original order with 200 OK. A new order returns 201 Created.

Core fields

Field	Type	Required	Description
`items`	array	Yes	One or more product or fee lines
`payment_method`	enum	No	Defaults to `cash`
`amount_paid`	number	No	Amount already collected
`discount_amount`	number	No	Order-level discount
`promotion_id`	uuid	No	Promotion applied to the order
`customer_id`	uuid	No	Existing customer
`customer_name`	string	No	Finds or creates a customer when no ID is supplied
`store_id`	uuid	No	Store used for inventory and reporting
`store_name`	string	No	Store name when integrating by name
`channel`	enum	No	Source channel for the order
`tags`	string array	No	Tag IDs, slugs, or names
`notes`	string	No	Order note, up to 2,000 characters
`scheduled_for`	ISO timestamp	No	Future fulfillment time
`occurred_at`	ISO timestamp	No	Original sale time when importing historical orders

Valid channels are in_person, whatsapp, instagram, tiktok, telegram, twitter, storefront, dashboard, checkout, voice, and other.

Line item fields

Field	Type	Required	Description
`product_name`	string	Yes	Display name captured on the order
`quantity`	number	Yes	Positive quantity
`product_id`	uuid	Product lines	Catalog product used for pricing and inventory
`variant_id`	uuid	No	Selected product variant
`custom_price`	number	No	Unit price override
`line_type`	enum	No	`product` or `fee`, default `product`
`modifiers`	array	No	Selected modifier options

Catalog-backed lines should include product_id. Fee lines can omit it and use line_type: "fee" with a custom_price.

Modifier fields

Field	Type	Required	Description
`modifier_group_id`	uuid	Yes	Product modifier group
`modifier_option_id`	uuid	Yes	Selected option
`name`	string	Yes	Snapshot label shown on the order
`price_delta`	number	No	Expected price addition; server catalog rules remain authoritative

Restaurant and hotel fields

Field	Type	Description
`service_mode`	enum	`dine_in`, `takeaway`, or `room_service`
`service_charge_amount`	number	Service charge applied to the order
`table_session_id`	uuid	Active restaurant table session
`table_label`	string	Table label when no session is supplied
`covers`	integer	Number of guests
`send_to_kitchen`	boolean	Route the order to the kitchen workflow
`served_by_user_id`	uuid	Server or waiter responsible for the order
`hotel_reservation_id`	uuid	Reservation receiving the order
`hotel_room_id`	uuid	Room receiving the order

School field

academic_term_id associates the order with an academic term. It is optional for other business types.

Product and variant example


{
  "items": [
    {
      "product_id": "7a59174f-3207-42a6-8fab-5b8d8b2929fb",
      "variant_id": "f91718fb-1487-4ada-a44c-794b1ba5a3d3",
      "product_name": "Jollof Rice",
      "quantity": 2,
      "modifiers": [
        {
          "modifier_group_id": "4f7f9ff4-19e4-4cbb-b7c6-45275e70fc6f",
          "modifier_option_id": "f494ef42-178a-4e16-bcf2-481a52d55833",
          "name": "Extra chicken",
          "price_delta": 1000
        }
      ]
    }
  ],
  "payment_method": "transfer",
  "amount_paid": 4000,
  "discount_amount": 1000,
  "customer_id": "3cadb42d-571b-4979-94b4-c094c60820c4",
  "store_id": "837ceae4-43c2-4bbb-830c-1099d36b9d05",
  "channel": "checkout",
  "service_mode": "takeaway",
  "notes": "Pack cutlery separately"
}

Fee line example


{
  "items": [
    {
      "product_name": "Delivery fee",
      "quantity": 1,
      "custom_price": 1500,
      "line_type": "fee"
    }
  ],
  "payment_method": "cash"
}

Scheduled order example


{
  "items": [
    {
      "product_id": "7a59174f-3207-42a6-8fab-5b8d8b2929fb",
      "product_name": "Event platter",
      "quantity": 3
    }
  ],
  "scheduled_for": "2026-08-20T18:30:00.000Z",
  "customer_name": "Grace Hopper",
  "channel": "voice"
}

scheduled_for must be a valid future timestamp. The new order enters scheduled status.

Update an order


PATCH /v1/orders/5037c85a-44c6-4c3a-bd7d-3e21e73915e1
Content-Type: application/json

Only supplied fields are changed.

Field	Type	Description
`status`	enum	`scheduled`, `pending`, `completed`, or `cancelled`
`customer_id`	uuid	Assign an existing customer
`customer_name`	string	Find or create a customer by name
`payment_method`	enum	Change the recorded payment method
`amount_paid`	number	Set the cumulative amount collected
`total_amount`	number	Correct the order total
`academic_term_id`	uuid or null	Assign or clear an academic term
`scheduled_for`	ISO timestamp or null	Schedule a recent order or update its schedule
`cancellation_reason`	string	Reason stored when changing to `cancelled`
`channel_fulfilled`	boolean	Mark a WhatsApp or Voice order treated or reopen it

Record a partial payment


{
  "payment_method": "transfer",
  "amount_paid": 4000
}

amount_paid is cumulative. If an order total is 7000 and a second payment brings the collected amount to 7000, send 7000, not the payment delta.

Cancel an order


{
  "status": "cancelled",
  "cancellation_reason": "Customer changed their mind"
}

The response includes the stored cancellation audit block. Completed automated bank transfer orders cannot be cancelled through this endpoint because a payment reversal may be required.

Mark a channel order fulfilled


{
  "channel_fulfilled": true
}

Send false to return the order to the channel fulfillment queue.

Confirm a scheduled order


POST /v1/orders/5037c85a-44c6-4c3a-bd7d-3e21e73915e1/confirm
Idempotency-Key: b802662c-3b05-4f9b-859c-14468eb6d485
Content-Type: application/json


{
  "payment_method": "pos",
  "amount_paid": 7000
}

Field	Type	Description
`payment_method`	enum	Final payment method
`amount_paid`	number	Amount collected; defaults to the full order total

A fully paid order becomes completed. A partially paid order becomes pending. Only orders currently in scheduled status can be confirmed.

Refresh an automated payment


POST /v1/orders/5037c85a-44c6-4c3a-bd7d-3e21e73915e1/requery

Use this endpoint for an order with isAutomated: true when your application needs to refresh its virtual account payment state. The response returns the updated order resource.

Do not poll continuously. Prefer webhooks for normal payment updates and requery only after a customer reports payment or when recovering from a missed event.

Generate a receipt


POST /v1/orders/5037c85a-44c6-4c3a-bd7d-3e21e73915e1/receipt


{
  "message": "Order receipt generated",
  "data": {
    "url": "https://storage.example.com/receipts/signed-receipt.pdf"
  }
}

Receipt URLs can be signed and time-limited. Store the order ID and generate another URL when a previous link expires.

Delete an order


DELETE /v1/orders/5037c85a-44c6-4c3a-bd7d-3e21e73915e1

Deletion soft-deletes the order, restores tracked variant inventory, and removes its active debt record. It is intended for incorrectly recorded orders.

Orders with automated deposits cannot be deleted and return 409 Conflict:


{
  "error": "order_not_deletable",
  "message": "Orders with automated deposits (like bank transfers) cannot be deleted."
}

Use cancellation for a valid order that will not be fulfilled. Use deletion only when the record itself should not remain in sales reporting.

Errors

HTTP status	Error	When it occurs
`400`	`request_failed`	A domain rule prevents the operation
`400`	`order_not_recorded`	Order creation fails
`401`	`unauthorized`	API key is missing or invalid
`403`	`forbidden`	API key lacks the required scope
`404`	`not_found`	Order is missing, deleted, or belongs to another business
`409`	`order_not_deletable`	An automated-deposit order cannot be deleted
`422`	`validation_error`	A request field or list filter is invalid
`429`	`rate_limit_exceeded`	Developer API rate limit is exceeded

See API conventions for the shared error envelope, retry rules, pagination, and idempotency behavior.

Creating an order emits an order.created webhook. Status and payment changes may emit additional order or payment events. Verify webhook signatures and process event IDs idempotently.