Order document
This document is returned by POST /v1/shop/orders/create and PUT /v1/shop/orders/{order}/items; lines, contact, delivery and totals in webhooks have the same shapes. An order is a snapshot: while it is draft it is the cart; once paid, nothing in it changes any more.
Example
Section titled “Example”{ "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b", "number": "261004-48213", "shop_id": "7f3c2b1a-0d9e-4f8a-b7c6-d5e4f3a2b1c0", "status": "draft", "redirect_url": "https://shop.example.com/cart?nc=1", "locale": "uk", "items": [ { "external_id": "SKU-1", "title": "Brit Care Adult Large Breed", "variant": "12 кг", "image_url": "https://shop.example.com/i/brit.jpg", "product_url": "https://shop.example.com/p/brit", "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", "variant": "400 мл", "image_url": "https://shop.example.com/i/bowl.jpg", "product_url": "https://shop.example.com/p/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": { "first_name": "Олена", "last_name": "Коваль", "phone": "+380671234567" }, "delivery": { "provider": "nova-poshta", "type": "branch", "data": { "city": { "id": "…", "external_id": "8d5a980d-391c-11dd-90d9-001a92567626", "name": "Київ" }, "branch": { "id": "…", "external_id": "1ec09d88-e1c2-11e3-8c4a-0050568002cf", "name": "Відділення №1: вул. Пирогівський шлях, 135" } }, "recipient": { "first_name": "Олена", "last_name": "Коваль", "phone": "+380671234567" } }, "totals": { "items_total": 313000, "discount_total": 17430, "total": 295570 }, "payment": { "id": "…", "status": "pending" }}All amounts are integer kopecks: 249000 means 2 490,00 ₴.
Top-level fields
Section titled “Top-level fields”| Field | Type | Description |
|---|---|---|
id |
string, UUID | Order identifier. Passed to NeocartsSubscription.open({ orderId }). |
number |
string | Human-readable number in the form YYMMDD-NNNNN: UTC date plus 5 random digits. Safe to show to the shopper and in emails. |
shop_id |
string, UUID | The shop that owns the order. |
status |
string | draft, pending_payment, paid, cancelled. Transitions are on the Statuses page. |
redirect_url |
string, nullable | Where the widget sends the shopper via “Back to the shop” after a finished order. Never given to the payment provider. |
locale |
string, nullable | uk or en — the language of emails to this shopper. |
items |
array | Cart lines, 1–50. See below. |
discount_percent |
integer, nullable | Subscription discount copied from the shop settings when the order was created. null — no discount. |
contact |
object, nullable | Shopper contact. null until the widget saves the contact step. |
delivery |
object, nullable | Delivery method and address. null until the widget saves the delivery step. |
totals |
object | Totals in kopecks. See below. |
payment |
object, nullable | Latest payment attempt, or null if checkout has not started. |
Line (items[])
Section titled “Line (items[])”| Field | Type | Description |
|---|---|---|
external_id |
string ≤255 | The product (variant, SKU) identifier in the shop. Must not contain /. |
title |
string ≤255 | Product title. |
variant |
string ≤255, nullable | Variant (“12 kg”, “400 ml”). |
image_url |
string, url ≤2048 | Image for the widget and emails. |
product_url |
string, url ≤2048 | Product page in the shop. |
price |
integer, kopecks | Unit price before discount as named by the shop server. 1–999999999. |
quantity |
integer | 1–9. |
mode |
string | one_time or subscription. |
interval_value |
integer, nullable | 1–365. Always null for one_time. |
interval_unit |
string, nullable | day or week. Always null for one_time. |
discounted_price |
integer, kopecks | Unit price after discount. Equals price for one_time. Formula in Money and rounding. |
subtotal |
integer, kopecks | price × quantity. |
total |
integer, kopecks | discounted_price × quantity. |
The discount applies to subscription lines only; one-time lines keep the full price.
Totals (totals)
Section titled “Totals (totals)”| Field | Type | Description |
|---|---|---|
items_total |
integer, kopecks | Sum of every line’s subtotal. |
discount_total |
integer, kopecks | items_total − total. |
total |
integer, kopecks | What the shopper pays today. Delivery cost is not included — the shopper pays the carrier. |
Contact (contact)
Section titled “Contact (contact)”| Field | Type | Description |
|---|---|---|
first_name |
string | First name. |
last_name |
string | Last name. |
email |
string | Order and subscription emails go here. |
phone |
string | International format, +380…. |
Delivery (delivery)
Section titled “Delivery (delivery)”| Field | Type | Description |
|---|---|---|
provider |
string | Carrier, one of those enabled in the shop. Today nova-poshta. |
type |
string | branch, parcel-locker or address; must be enabled for that carrier. |
data |
object | The address; fields depend on the method, see the table below. City, branch, parcel locker and street are { id, external_id, name } objects: id is the Neocarts id, external_id the carrier’s own (Nova Poshta Ref, used to create a waybill), name the name. If an entry is gone from the carrier’s directory, external_id and name are null. |
recipient |
object | Recipient first_name, last_name, phone. |
delivery.data shapes
Section titled “delivery.data shapes”| Method | data fields |
|---|---|
nova-poshta / branch |
city, branch |
nova-poshta / parcel-locker |
city, parcel_locker |
nova-poshta / address |
city, street, house_number; optional apartment_number, floor_number |
ukr-poshta / branch |
zip_code (numeric) |
Ukrposhta is disabled today; the shape is listed for completeness. Contact and delivery are filled in by the shopper in the widget — the shop server does not send them.
Payment (payment)
Section titled “Payment (payment)”| Field | Type | Description |
|---|---|---|
id |
string | Payment attempt identifier. |
status |
string | pending, success, failed, expired, refunded. One attempt is one payment; retrying checkout creates a new attempt. |
Who may change what
Section titled “Who may change what”| Part of the document | Shop server (Shop API) | Shopper in the widget |
|---|---|---|
items, redirect_url, locale |
Set at creation. items can be replaced wholesale with PUT …/items, only while status = draft. |
Never. |
contact, delivery |
Never. | On the “Contact” and “Delivery” steps, while the order is draft or pending_payment. |
discount_percent |
Copied from the shop settings at creation; later setting changes do not reprice open orders. | Never. |
status, payment, totals |
Read only. | Read only; status and payment change when the shopper goes on to payment and pays. |
A discount field sent on a request line is ignored: the discount is a shop setting, not a line property.
Nullability in short
Section titled “Nullability in short”contact,delivery,payment—nulluntil the matching step.redirect_url,locale,discount_percent,variant—nullwhen not set.interval_value,interval_unit—nullforone_time, even if sent in the request.totalsand all money fields on lines are always present and always integers.