CartDocs

Orders API

Paid plans

List 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=50

Orders come newest first. Filters:

ParameterValues
statuspending_payment, partially_paid, paid, partially_fulfilled, fulfilled, completed, cancelled, partially_refunded, refunded
customer_idcus_...
flagAn 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 } ]
}
  • reason is required, up to 255 characters.
  • lines refund whole order lines; add amount_minor to a line to refund only part of its price.
  • shipping refunds 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 of email for a registered customer. Their own cart must be empty.
  • A line can also be a free line: name, unit_price_minor and quantity.
  • shipping_method_ids picks the shipping method per parcel; without it, the first method offered is used.
  • payment_method_id picks the payment method; without it, the first one offered is used.
  • mark_paid: true records an offline payment at once and needs Confirm offline payments.

Needs Create orders for customers.

Updated 13 November 2026