Orders
A cart is an order in draft. Your server opens it with the basket as the shopper assembled it, and replaces the basket if it changes before checkout. The widget never changes the items — it only walks the shopper through contact, delivery and payment.
Prices never come from the browser. Your server sets them when it opens the cart. The price of a line is what the order charges and what the subscription created from that line keeps charging. Money is always integer kopecks: 249000 means 2 490,00 ₴.
An order must hold at least one subscription line: a basket of one-off items only is the shop’s own checkout, and Neocarts stays out of it. The subscriber discount is a shop setting — one sent on a line is ignored.
Create an order
Section titled “Create an order”Opens the cart and returns the order document with prices worked out. Every line is also written to the catalogue exactly as PUT /v1/shop/products/{external_id} would write it — except for price, which stays on the order and on the subscription the line creates.
Headers as described in Authentication: Authorization: Bearer nc_live_…, Accept-Language, Content-Type: application/json.
| Field | Type | Rules |
|---|---|---|
redirect_url |
string | optional, nullable, url ≤ 2048 — the address of the “Back to the shop” button on the success screen. Never given to the payment provider |
locale |
string | required, uk | en — the language of every email to this shopper. Only you know what your shopper reads, so there is no default. Stored on the customer with their first order and kept afterwards |
items |
array | required, 1 to 50 lines, at least one subscription |
items.*.external_id |
string | required, ≤ 255 — the product id in the shop (SKU) |
items.*.title |
string | required, ≤ 255 |
items.*.variant |
string | optional, nullable, ≤ 255 |
items.*.image_url |
string | required, url ≤ 2048 |
items.*.product_url |
string | required, url ≤ 2048 |
items.*.price |
integer | required, 1 to 999999999 — kopecks, before discount |
items.*.quantity |
integer | required, 1 to 9 |
items.*.mode |
string | required, one_time | subscription |
items.*.interval_value |
integer | required for subscription, 1 to 365; dropped for one_time |
items.*.interval_unit |
string | required for subscription, day | week; dropped for one_time |
The interval of a one_time line is dropped and echoed back as null.
curl -X POST https://core.neocarts.com/v1/shop/orders/create \ -H "Authorization: Bearer nc_live_…" \ -H "Accept-Language: en" \ -H "Content-Type: application/json" \ -d '{ "redirect_url": "https://shop.example.com/cart?neocarts=checkout", "locale": "en", "items": [ { "external_id": "SKU-1", "title": "Brit Care Adult Large Breed", "variant": "12 kg", "image_url": "https://shop.example.com/images/brit-care.jpg", "product_url": "https://shop.example.com/products/brit-care", "price": 249000, "quantity": 1, "mode": "subscription", "interval_value": 4, "interval_unit": "week" }, { "external_id": "SKU-2", "title": "Trixie ceramic bowl", "variant": "400 ml", "image_url": "https://shop.example.com/images/trixie-bowl.jpg", "product_url": "https://shop.example.com/products/trixie-bowl", "price": 32000, "quantity": 2, "mode": "one_time" } ] }'// items — the cart lines with mode / interval_* merged in, e.g. from NeocartsSubscription.getOrderItems(...)const response = await fetch('https://core.neocarts.com/v1/shop/orders/create', { method: 'POST', headers: { Authorization: 'Bearer nc_live_…', 'Accept-Language': 'en', 'Content-Type': 'application/json', }, body: JSON.stringify({ redirect_url: 'https://shop.example.com/cart?neocarts=checkout', locale: 'en', items, }),});const order = await response.json();// order.id — for the widget; order.number — for peopleThe response is the order document, the same one the widget reads (abridged; every field is described in Order document):
{ "id": "0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b", "number": "261004-48213", "shop_id": "…", "status": "draft", "redirect_url": "https://shop.example.com/cart?neocarts=checkout", "locale": "en", "items": [ { "external_id": "SKU-1", "title": "Brit Care Adult Large Breed", "variant": "12 kg", "image_url": "https://shop.example.com/images/brit-care.jpg", "product_url": "https://shop.example.com/products/brit-care", "price": 249000, "quantity": 1, "mode": "subscription", "interval_value": 4, "interval_unit": "week", "discounted_price": 231570, "subtotal": 249000, "total": 231570 }, { "external_id": "SKU-2", "title": "Trixie ceramic bowl", "variant": "400 ml", "image_url": "https://shop.example.com/images/trixie-bowl.jpg", "product_url": "https://shop.example.com/products/trixie-bowl", "price": 32000, "quantity": 2, "mode": "one_time", "interval_value": null, "interval_unit": null, "discounted_price": 32000, "subtotal": 64000, "total": 64000 } ], "discount_percent": 7, "contact": null, "delivery": null, "totals": { "items_total": 313000, "discount_total": 17430, "total": 295570 }, "payment": null}Keep id for the widget; show number to people. The discount applies to subscription lines only and is worked out by the rules in Money and rounding.
| Status | When |
|---|---|
201 |
order opened — the response is the order document |
401 |
no or unknown key |
422 |
validation — errors keyed by the literal field path, e.g. items.0.price or locale |
What to do on error: 401 — stop and check the key; 422 — fix the body by the field named in errors; the usual causes are a missing locale, a price with a fractional part instead of integer kopecks, or a basket without a single subscription line.
Replace the order’s items
Section titled “Replace the order’s items”Replaces the basket wholesale and reprices it with the discount the order was opened with. Call it when the shopper changed the cart after your server opened the order but before checkout started.
Headers — the same as above. {order} is the order’s id from the create response.
| Field | Type | Rules |
|---|---|---|
items |
array | required, 1 to 50 lines, at least one subscription; line rules are the same as on create |
curl -X PUT https://core.neocarts.com/v1/shop/orders/0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b/items \ -H "Authorization: Bearer nc_live_…" \ -H "Accept-Language: en" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "external_id": "SKU-1", "title": "Brit Care Adult Large Breed", "variant": "12 kg", "image_url": "https://shop.example.com/images/brit-care.jpg", "product_url": "https://shop.example.com/products/brit-care", "price": 249000, "quantity": 2, "mode": "subscription", "interval_value": 4, "interval_unit": "week" } ] }'const response = await fetch(`https://core.neocarts.com/v1/shop/orders/${orderId}/items`, { method: 'PUT', headers: { Authorization: 'Bearer nc_live_…', 'Accept-Language': 'en', 'Content-Type': 'application/json', }, body: JSON.stringify({ items }),});
if (response.status === 409) { // the order is no longer a draft — open a new one and hand the widget the new id}const order = await response.json();The response is the updated order document, shaped exactly as on create.
| Status | When |
|---|---|
200 |
basket replaced — the response is the order document |
401 |
no or unknown key |
404 |
unknown order, or another shop’s — {"message":"Not found."} |
409 |
the order is no longer a draft: checkout has started — {"message":"The items of an order in checkout can no longer be changed."}; or it was cancelled — {"message":"This order has been cancelled."} |
422 |
validation — errors keyed by the literal path, e.g. items.0.price |
What to do on error: 404 and 409 — open a new order and hand the widget the new id; 422 — fix the line errors points at.
Why items freeze
Section titled “Why items freeze”Once the shopper presses “Go to payment”, the order becomes pending_payment and its items no longer change — even if the payment fails. That way an open payment page with the old total cannot buy a different basket. Transitions are in Statuses.
Hand the order to the widget
Section titled “Hand the order to the widget”The shop’s page needs only the order id from the server. Return it to the page and call NeocartsSubscription.open({ orderId }) — from there the widget walks the shopper through contact, delivery and payment. Your server learns the outcome from webhooks. How to do it on the page is in Checkout.