API · OrdersDocs navigation

Orders API

Nothing is pushed to you: poll the list for new orders. Delivering an order twice delivers it once.

On this page
StatusMeaning
pendingInvoice created, no confirmed payment yet
paidPayment confirmed, delivery not finished
deliveredStock was handed to the buyer
underpaidThe buyer sent less than the invoice
out_of_stockPaid, but there was not enough stock to deliver
preorderedPaid in advance and waiting for a restock
refundedRefunded to the customer
expiredThe invoice ran out before it was paid
failedThe 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

Scope read_orders

Lists orders, newest first. This is the call to poll: Shoplio does not push order events to you.

ParameterTypeInRules
statusstringqueryOne status value, matched exactly. See the status table
searchstringqueryMatches part of the customer email, the order id or the order notes
pageintegerqueryFrom 1. Default 1
limitintegerqueryDefault 20, maximum 100
Request
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

Scope read_orders

Returns one order with its product, its payments and, once it is delivered, the content the buyer received.

ParameterTypeInRules
id requiredstringpathOrder id (UUID)
Request
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 fieldTypeNotes
statusstringOne of the nine status values
amountnumberThe USD total the buyer was invoiced
currencystringThe currency label of the order
crypto_amountnumberThe amount in the coin the invoice was for
crypto_currencystringCoin ticker
quantityintegerUnits ordered
customer_emailstringThe email the buyer gave at checkout
customer_idstring or nullThe store account that placed the order. null for a guest
variant_namestringThe variant bought. Empty when the product has none
notesstringOrder notes
created_at, paid_at, delivered_atstring or nullTimestamps. null until the event has happened
productobjectThe product object
paymentsarrayThe payment records of the order
fee_surchargenumberPresent only when a "Payment processing fee" was added to the order. amount includes it
delivered_contentstringPresent only when status is delivered. Decrypted: exactly what the buyer received
payment_methodstringPresent on card orders only, with the value "card"
cardobjectPresent 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.
ErrorStatusWhen
Order not found404No order with that id in this shop.

Deliver an order

POST /orders/:id/deliver

Scope fulfill_orders · Also limited to 60 requests a minute in its own bucket

Delivers one paid, pre-ordered or out-of-stock order from your stock. It takes no request body.

ParameterTypeInRules
id requiredstringpathOrder id (UUID)
Request
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.
ErrorStatusWhen
Order not found404No order with that id in this shop.
insufficient_stock Not enough stock to deliver this order. Add stock and try again.409There are fewer unsold items than the order needs. The order is left as it was.
in_progress This order is already being processed. Check it again in a moment.409Another delivery attempt holds the order.
already_manually_processed This order has already been manually processed409An out-of-stock order that was already delivered by hand.
status_changed This order's status changed while it was being delivered; it was not delivered409The order moved during the call, for example an automatic refund landed first.
card_payment_reversed This card payment was refunded or disputed409An out-of-stock card order whose payment was reversed. It can be delivered only from the dashboard.
not_deliverable Only paid, pre-ordered or out-of-stock orders can be delivered via the API.422The order is pending, underpaid, expired, failed or refunded.
no_product This order has no product to deliver422A payment-link order or a balance top-up.
product_unavailable This order's product no longer exists422The product was deleted.

If the docs do not cover it, ask on Telegram or use the contact form.