Orders

Read your order history and record new sales - for example, to push point-of-sale or third-party orders into Cloove.

All endpoints share the prefix /v1/orders and authenticate with an API key.

Endpoint	Scope
`GET /v1/orders`	`orders:read`
`GET /v1/orders/:id`	`orders:read`
`POST /v1/orders`	`orders:write`

List orders


GET /v1/orders

Query parameters

Parameter	Type	Description
`status`	string	Comma-separated statuses to include
`customer_id`	uuid	Filter by customer
`store_id`	uuid	Filter by store
`start_date`	ISO date	Only orders on/after this date
`end_date`	ISO date	Only orders on/before this date
`page`	number	Page number (default `1`)
`limit`	number	Items per page (default `50`)


{
  "message": "Orders retrieved",
  "data": [
    {
      "id": "o1a2b3c4-...",
      "shortCode": "ORD-1234",
      "status": "COMPLETED",
      "totalAmount": 5000,
      "amountPaid": 5000,
      "remainingAmount": 0,
      "paymentMethod": "CASH",
      "customer": { "id": "ct1a2b3c-...", "name": "Ada Lovelace" },
      "date": "2026-01-15T10:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "perPage": 50, "totalPages": 1, "hasMore": false }
}

Get an order


GET /v1/orders/:id

Returns a single order with its line items. Responds 404 not_found if the ID doesn’t belong to your business.

Record an order


POST /v1/orders

Records a sale. Always send an Idempotency-Key header - recording is a money-affecting write, and the key guarantees a retry won’t double-count the sale.

Body

Field	Type	Required	Description
`items`	array	Yes	One or more line items (see below)
`payment_method`	string	No	e.g. `CASH`, `TRANSFER` (defaults to `CASH`)
`amount_paid`	number	No	Amount collected; less than the total creates a credit sale
`discount_amount`	number	No	Discount applied to the order
`customer_id`	uuid	No	Link to an existing contact
`customer_name`	string	No	Name when no `customer_id` is provided
`store_id`	uuid	No	Store the sale belongs to
`channel`	string	No	Sales channel label
`notes`	string	No	Free-text note

Line item

Field	Type	Required	Description
`product_name`	string	Yes	Product name
`quantity`	number	Yes	Quantity sold
`product_id`	uuid	No	Link to a catalog product
`variant_id`	uuid	No	Specific variant
`custom_price`	number	No	Override the unit price


{
  "items": [
    { "product_id": "p1a2b3c4-...", "product_name": "Jollof Rice", "quantity": 2 }
  ],
  "payment_method": "CASH",
  "amount_paid": 5000,
  "customer_id": "ct1a2b3c-...",
  "channel": "api"
}

Response 201 Created - the recorded order.

Recording an order emits an order.created webhook, so downstream systems can react in real time.