Receiving & Managing Orders

How orders reach you

When a customer places and pays for an order, Chowdeck sends a webhook event to your configured webhook URL with the category ORDER_CREATED. This is your trigger to act on the order.

Make sure you have a webhook URL configured on your merchant account. See the Webhooks guide for setup instructions.

The order lifecycle

Every order moves through the following states:

Your job as a merchant is to move the order from received → preparing → awaiting_pickup. Chowdeck handles the rest.

If your store manages its own deliveries (vendor-managed delivery) instead of using a Chowdeck rider, marking an order as ready moves it directly to in_transit, skipping the awaiting_pickup stage.

1. Receive the order

When you receive an ORDER_CREATED webhook, fetch the full order details using your merchantReference and the orderReference from the webhook payload.

curl --request GET \
  --url https://api.chowdeck.com/merchant/{merchantReference}/order/{orderReference} \
  --header 'Authorization: Bearer YOUR_API_KEY'

A successful response looks like this:

{
  "status": "success",
  "data": {
    "id": 10234,
    "reference": "ORD-ABC123",
    "status": "received",
    "items": [...],
    "total_price": 450000,
    "currency": "NGN"
  }
}

total_price is in the smallest currency unit. Divide by 100 to get the display value (e.g. 450000 = ₦4,500).

2. Accept or reject the order

Once you've reviewed the order, you must either accept or reject it.

Accept orders early enough — if an order sits without a response, Chowdeck will auto-reject it on your behalf and the customer will be refunded.

Accept

curl --request PUT \
  --url https://api.chowdeck.com/merchant/{merchantReference}/order/{orderReference}/accept \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "preparation_duration": 15
  }'

Request body:

A successful response returns the updated order object with status: "preparing".

Reject

If you cannot fulfil the order, reject it with a reason. The customer is notified and refunded automatically.

curl --request PUT \
  --url https://api.chowdeck.com/merchant/{merchantReference}/order/{orderReference}/reject \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "reason": "Item out of stock"
  }'

3. Mark the order as ready

Once you have prepared the order, mark it as ready for pickup. This notifies the assigned rider to come collect.

curl --request PUT \
  --url https://api.chowdeck.com/merchant/{merchantReference}/order/{orderReference}/ready \
  --header 'Authorization: Bearer YOUR_API_KEY'

If you mark an order as ready immediately after accepting, the request may be rejected. Allow a brief moment before calling this endpoint.

Handling item substitutions

If one or more items in an order are unavailable, you can propose substitutions instead of rejecting the whole order. The customer will be notified and asked to approve the change.

curl --request POST \
  --url https://api.chowdeck.com/merchant/{merchantReference}/order/{orderReference}/substitution \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "substitutions": [
      {
        "item_reference": "MENU-REF-123",
        "order_item_type": "menu",
        "quantity_unavailable": 1,
        "pack_id": 1,
        "replacements": [
          {
            "reference": "MENU-REF-456",
            "quantity": 1
          }
        ]
      }
    ]
  }'

Substitution object fields:

Error responses

All failed requests return this shape:

{
  "status": "failed",
  "message": "..."
}

Listing orders

You can fetch a paginated list of all orders for your store, with optional filters.

curl --request GET \
  --url 'https://api.chowdeck.com/merchant/{merchantReference}/order?page=1&per_page=50' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Supported query parameters: