Orders API
Nothing is pushed to you: poll the list for new orders. Delivering an order twice delivers it once.
On this page
| Status | Meaning |
|---|---|
pending | Invoice created, no confirmed payment yet |
paid | Payment confirmed, delivery not finished |
delivered | Stock was handed to the buyer |
underpaid | The buyer sent less than the invoice |
out_of_stock | Paid, but there was not enough stock to deliver |
preordered | Paid in advance and waiting for a restock |
refunded | Refunded to the customer |
expired | The invoice ran out before it was paid |
failed | The payment failed |
What each status asks of you is in Order statuses and manual delivery.
Card orders
A card order carries payment_method with the value card and a card object. The money for it is in your ServerSide account. See Card payments.
List orders
GET /orders
Lists orders, newest first. This is the call to poll: Shoplio does not push order events to you.
| Parameter | Type | In | Rules |
|---|---|---|---|
status | string | query | One status value, matched exactly. See the status table |
search | string | query | Matches part of the customer email, the order id or the order notes |
page | integer | query | From 1. Default 1 |
limit | integer | query | Default 20, maximum 100 |
curl -H "Authorization: Bearer YOUR_KEY" \ "https://api.shopl.io/api/v1/orders?status=delivered&page=1"
200 OK { "success": true, "data": { "orders": [ { "id": "ab059f8a-6c1d-4e2b-b3a4-9d8c7e6f5a41", "shop_id": "3f2a9c1b-7d44-4e0a-9a3c-1f5b8e2d6c70", "product_id": "a1b2c3d4-0c1e-4f7a-8b21-5d9e3c7f1a02", "customer_email": "[email protected]", "quantity": 1, "amount": 7.49, "currency": "USD", "crypto_currency": "USDT", "crypto_amount": 7.49, "status": "delivered", "manually_processed": false, "paid_at": "2026-06-28T18:05:02Z", "delivered_at": "2026-06-28T18:05:11Z", "created_at": "2026-06-28T18:04:00Z" } ], "total": 1392, "page": 1, "limit": 20 } }
- A list entry never carries the delivered content. Read one order for that.
- A list entry is the whole order record, so it has more keys than GET /api/v1/orders/:id returns: among them shop_id, product_id, payment_id, payment_method, discount_amount and manually_processed.
Get an order
GET /orders/:id
Returns one order with its product, its payments and, once it is delivered, the content the buyer received.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Order id (UUID) |
curl -H "Authorization: Bearer YOUR_KEY" \ https://api.shopl.io/api/v1/orders/ORDER_ID
200 OK { "success": true, "data": { "id": "ab059f8a-6c1d-4e2b-b3a4-9d8c7e6f5a41", "status": "delivered", "amount": 7.49, "currency": "USD", "crypto_amount": 7.49, "crypto_currency": "USDT", "quantity": 1, "customer_email": "[email protected]", "customer_id": null, "variant_name": "", "notes": "", "created_at": "2026-06-28T18:04:00Z", "paid_at": "2026-06-28T18:05:02Z", "delivered_at": "2026-06-28T18:05:11Z", "delivered_content": "XXXXX-YYYYY-ZZZZZ" } }
| Response field | Type | Notes |
|---|---|---|
status | string | One of the nine status values |
amount | number | The USD total the buyer was invoiced |
currency | string | The currency label of the order |
crypto_amount | number | The amount in the coin the invoice was for |
crypto_currency | string | Coin ticker |
quantity | integer | Units ordered |
customer_email | string | The email the buyer gave at checkout |
customer_id | string or null | The store account that placed the order. null for a guest |
variant_name | string | The variant bought. Empty when the product has none |
notes | string | Order notes |
created_at, paid_at, delivered_at | string or null | Timestamps. null until the event has happened |
product | object | The product object |
payments | array | The payment records of the order |
fee_surcharge | number | Present only when a "Payment processing fee" was added to the order. amount includes it |
delivered_content | string | Present only when status is delivered. Decrypted: exactly what the buyer received |
payment_method | string | Present on card orders only, with the value "card" |
card | object | Present on card orders only: provider, status, refunded_amount (a string), dispute_status and reversal |
- Treat a key with read_orders as holding your sold inventory: it can read every delivered item.
Deliver an order
POST /orders/:id/deliver
Delivers one paid, pre-ordered or out-of-stock order from your stock. It takes no request body.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Order id (UUID) |
curl -X POST \ -H "Authorization: Bearer YOUR_KEY" \ https://api.shopl.io/api/v1/orders/ORDER_ID/deliver
200 OK { "success": true, "data": { "order_id": "ab059f8a-6c1d-4e2b-b3a4-9d8c7e6f5a41", "status": "delivered", "already_delivered": false } }
- Safe to repeat: a delivered order answers 200 with "already_delivered": true and nothing more is delivered.
- 202 with "in_progress": true means another attempt holds the order. Read the order again shortly.
- A refusal carries data.code, data.order_id and data.status next to the error text.
- Stock is checked first, so a paid order with too little stock answers 409 and stays paid.
- The response never includes the delivered content. Read it with GET /api/v1/orders/:id.
- An order that is not paid in full can be delivered only from the dashboard.