Skip to content

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.

{
"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": "Коваль",
"email": "[email protected]",
"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 ₴.

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

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

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

  • contact, delivery, payment — null until the matching step.
  • redirect_url, locale, discount_percent, variant — null when not set.
  • interval_value, interval_unit — null for one_time, even if sent in the request.
  • totals and all money fields on lines are always present and always integers.