Orders API2026-11Preview

Orders

A sale of yours that we buy from the seller, check and photograph in our warehouse, pack in your box and ship to your customer.

Follow an order with webhooks rather than polling: order events fire as each step happens. The parcel itself is a fulfillment order, then a shipment.

Endpoints

POST/v1/ordersCreate an order
GET/v1/ordersList orders
GET/v1/orders/{id}Retrieve an order
POST/v1/orders/{id}/cancelCancel an order

The Order object

idstring: Starts ord_.
external_idstring: Your store's order number. Unique on your account.
sourcestring: api, or shopify for orders your Shopify store sent us.
statusstring: The least-far line's status; see Statuses below.
payment_statusstring: awaiting_payment, paid, partially_refunded or refunded.
lanestring: saver or fast.
lines[]array: Variant, quantity, units bought per item, status, the warehouse photos once checked, and reason when turned down.
ship_toobject: Your customer's name, address, phone and email.
packagingstring|null: Your branded box or mailer; your default when null.
chargesobject: What it costs, in CN¥: the procurement (goods, intake fee, tax) and the parcel (shipping, handling fee, tax). The parcel is an estimate from your weights until we weigh it.
amount_duemoney|null: What your balance still has to cover, while awaiting_payment.
fulfillment_orders[]array: The parcels it leaves in.

order

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "shopify",
  "status": "checked",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "checked",
      "photos": [
        "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
        "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
      ],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": ["fo_7k2m"],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

Send one of your store's orders to us. Each line is a variant you saved, or a listing link and SKU we buy as is. The order is paid from your balance at once; one your balance cannot cover is still created, as awaiting_payment with amount_due, and goes ahead by itself when you top up.

Orders from your Shopify store reach us without this call. Use it for WooCommerce, Wix, your own site, or anything else that sells.

Scopeorders:write

Body

external_idstringrequired: Your order number. A second order with it is refused.
lines[]arrayrequired: variant and quantity, or url, sku and quantity. units (optional) buys that many per item, for packs.
ship_toobjectrequired: name, line1, line2, city, region, postal_code, country (two letters), phone, email.
lanestring: saver or fast. saver when left out.
packagingstring: Optional. A packaging id; your default when left out.
notestring: Optional. For our warehouse team, up to 500 characters.

Errors

Status	Type	When
400	bad-body	A field is missing or wrong; errors[] points at it.
409	duplicate-order	external_id is already an order; order names it.
422	unprocessable	A line's variant is sold out, or its link cannot be read.
422	not-shippable	No published rate reaches ship_to.country on that lane.

curl -X POST "https://www.ninjabuy.com/api/v1/orders" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "1012",
    "lines": [{ "variant": "var_41hz", "quantity": 1 }],
    "ship_to": {
      "name": "Sam Rivera",
      "line1": "500 Congress Ave",
      "city": "Austin",
      "region": "TX",
      "postal_code": "78701",
      "country": "US",
      "phone": "+15125550142",
      "email": "sam@example.com"
    },
    "lane": "saver"
  }'

Response 201

HTTP/2 201 Created

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "api",
  "status": "buying",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "buying",
      "photos": [],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": [],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

List orders

GET/v1/orders

Newest first.

Scopeorders:read

Query parameters

statusstring: Optional. One of the statuses below.
sourcestring: Optional. api or shopify.
external_idstring: Optional. Find one by your own order number.
created_sincestring: Optional. A time.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/orders?status=checked" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "ord_3n7q",
      "external_id": "1012",
      "status": "checked",
      "payment_status": "paid"
    }
  ],
  "has_more": false,
  "cursor": null
}

Retrieve an order

GET/v1/orders/{id}

Every line's status, its warehouse photos once checked, what it cost and its parcels.

Scopeorders:read

Path parameters

idstringrequired: The order's id.

Errors

Status	Type	When
404	not-found	No such order on this account.

curl "https://www.ninjabuy.com/api/v1/orders/ord_3n7q" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "shopify",
  "status": "checked",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "checked",
      "photos": [
        "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
        "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
      ],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": ["fo_7k2m"],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

Cancel an order

POST/v1/orders/{id}/cancel

Before we buy, the whole order is refunded to your balance. Once bought, the lines the seller takes back are refunded and the rest stay on your shelf as warehouse stock. A shipped order cannot be cancelled.

Scopeorders:write

Path parameters

idstringrequired: The order's id.

Body

reasonstring: Optional. Kept on the order.

Errors

Status	Type	When
404	not-found	No such order on this account.
409	invalid-state	It has shipped.

curl -X POST "https://www.ninjabuy.com/api/v1/orders/ord_3n7q/cancel" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer changed their mind" }'

Response 200

HTTP/2 200 OK

{
  "id": "ord_3n7q",
  "status": "cancelled",
  "payment_status": "refunded",
  "refunded": { "amount": "191.52", "currency": "CNY" }
}

Statuses

Each line has its own status; an order's is its least-far line's. In order:

Status	Meaning
awaiting_payment	Your balance did not cover it. Top up and it goes ahead by itself.
buying	Paid; we are buying it from the seller.
with_seller	Bought; the seller has not sent it to our warehouse yet.
checked	In our warehouse, checked and photographed, waiting to be packed.
shipped	On its way, with tracking.
delivered	The carrier says it arrived.
rejected	We could not buy it (sold out, link gone); reason says why, and it is refunded.
cancelled	You cancelled it.

Money

In the samples, buying one unit costs CN¥57.00 and shipping it CN¥134.52, taken from your balance. What each line is: Fees.

The Order object

Create an order

Body

Errors

List orders

Query parameters

Retrieve an order

Path parameters

Errors

Cancel an order

Path parameters

Body

Errors

Statuses

Money