Orders API
Paid plansList and read orders, follow their timeline, add notes, record shipments, mark offline payments as paid, refund, cancel and place manual orders.
On this page
The orders calls cover the same work as Orders in the admin, with the same rules: a paid order is refunded, never cancelled, and money only moves when your payment provider confirms it. All examples leave out the Host: api.ixxocart.com and Authorization: Bearer ... headers, which every call needs. Every POST also needs an Idempotency-Key header (see Pagination, errors and limits).
List orders
GET /api/v1/orders?status=paid&limit=50Orders come newest first. Filters:
| Parameter | Values |
|---|---|
status | pending_payment, partially_paid, paid, partially_fulfilled, fulfilled, completed, cancelled, partially_refunded, refunded |
customer_id | cus_... |
flag | An order flag that is set, for example refund_required, stock_shortfall or late_payment |
Needs See orders.
Read one order
GET /api/v1/orders/ord_...The order holds its number, status, payment_status, currency, the dates (placed_at, paid_at, completed_at, cancelled_at), totals, the customer (customer_id, email, customer_name), the billing_address and shipping_address, its flags, and its parts: the shipment groups with their lines, and the payment parts with their amount and status.
Related reads:
GET /api/v1/orders/ord_.../events: the timeline, oldest first, with who did what, notes included.GET /api/v1/orders/ord_.../shipments: the shipment groups and parcels.GET /api/v1/orders/ord_.../invoices: the invoices of the order (needs See and download invoices and credit notes).
Add a note
POST /api/v1/orders/ord_.../notes
Content-Type: application/json
Idempotency-Key: 3a7c...
{ "body": "Customer asked for gift wrapping." }A note is up to 2000 characters and shows on the order's timeline for your staff only. Needs Write staff notes on orders.
Record a shipment
When a parcel leaves, record which lines are in it. Use the shipment group ID (shg_...) and the line IDs (oln_...) from the order:
POST /api/v1/orders/ord_.../shipment-groups/shg_.../fulfilments
Content-Type: application/json
Idempotency-Key: 8b21...
{
"lines": [ { "order_line_id": "oln_...", "quantity": 1 } ],
"carrier": "ACS",
"tracking_number": "1234567890",
"tracking_url": "https://www.acscourier.net/track?code=1234567890"
}The answer is 201 with the new shipment_id and the updated order. The customer gets the shipping e-mail, if it is switched on. Needs Record shipments and deliveries.
Mark an offline payment as paid
For bank transfer or cash on delivery, confirm the money arrived:
POST /api/v1/orders/ord_.../payment-parts/1/mark-paid
Content-Type: application/json
Idempotency-Key: 5c09...
{ "note": "Bank transfer received on 12 November" }The number in the path is the payment part's number from the order. The answer gives an outcome, such as paid or already_paid, and the order. A key needs a person behind it for this call, so a staff key works.
Refund
POST /api/v1/orders/ord_.../refunds
Content-Type: application/json
Idempotency-Key: 71fe...
{
"reason": "Arrived damaged",
"lines": [ { "order_line_id": "oln_...", "quantity": 1 } ]
}reasonis required, up to 255 characters.linesrefund whole order lines; addamount_minorto a line to refund only part of its price.shippingrefunds shipping per shipment group:{ "shg_...": 450 }.
The refund goes back through the payment provider the customer paid with. The answer is 201 with the refund_id and the order. A refund above what was paid is refused with 409. Needs Refund up to the support refund limit; a refund above that limit also needs Refund any amount.
Cancel or complete
POST /api/v1/orders/ord_.../cancel
Idempotency-Key: c4d2...Cancelling works only while nothing is paid: every unpaid payment part is cancelled and the stock goes back. Once any part is paid, you get 409 orders.part_already_paid. Refund the order instead.
POST /api/v1/orders/ord_.../complete marks an order completed once all its goods are out and no return is open. It needs Complete orders; cancelling needs Cancel unpaid orders.
Place a manual order
Staff can place an order for a registered customer or a guest e-mail, with the same checkout as a shopper's:
POST /api/v1/orders
Content-Type: application/json
Idempotency-Key: e902...
{
"email": "guest@example.com",
"lines": [ { "product_id": "prd_...", "quantity": 2 } ],
"billing_address": {
"first_name": "Maria", "last_name": "Ioannou",
"line1": "12 Makariou Avenue", "city": "Nicosia", "postcode": "1065", "country_code": "CY"
},
"same_address": true,
"mark_paid": false
}- Use
customer_id(cus_...) instead ofemailfor a registered customer. Their own cart must be empty. - A line can also be a free line:
name,unit_price_minorandquantity. shipping_method_idspicks the shipping method per parcel; without it, the first method offered is used.payment_method_idpicks the payment method; without it, the first one offered is used.mark_paid: truerecords an offline payment at once and needs Confirm offline payments.
Needs Create orders for customers.
Related
Updated 13 November 2026