Skip to content

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.

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.

POST/v1/shop/orders/createBearer: shop API key

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.

Terminal window
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"
}
]
}'

The 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.

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.

PUT/v1/shop/orders/{order}/itemsBearer: shop API key

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
Terminal window
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"
}
]
}'

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.

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.

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.