Замовлення
Кошик — це замовлення в статусі draft. Ваш сервер відкриває його з тим складом, який зібрав покупець, і замінює склад, якщо той змінився до оформлення. Віджет склад замовлення не змінює — він лише веде покупця через контакт, доставку й оплату.
Ціни ніколи не приходять із браузера. Їх задає ваш сервер, коли відкриває кошик. Ціна рядка — це сума, яку спише замовлення, а далі — підписка, створена з цього рядка. Гроші скрізь — цілі копійки: 249000 означає 2 490,00 ₴.
Замовлення мусить містити хоча б один рядок subscription: кошик лише з разових товарів — це власне оформлення магазину, Neocarts у ньому участі не бере. Знижка передплатника — налаштування магазину; надіслана в рядку знижка ігнорується.
Створити замовлення
Section titled “Створити замовлення”Відкриває кошик і повертає документ замовлення з розрахованими цінами. Кожен рядок водночас записується в каталог так само, як це зробив би PUT /v1/shop/products/{external_id}, — окрім price, яка залишається на замовленні та на підписці, яку створить цей рядок.
Заголовки — як описано в Автентифікації: Authorization: Bearer nc_live_…, Accept-Language, Content-Type: application/json.
| Поле | Тип | Правила |
|---|---|---|
redirect_url |
string | необовʼязкове, може бути null, url ≤ 2048 — адреса кнопки «Повернутися до магазину» на екрані успіху. Платіжній системі не передається |
locale |
string | обовʼязкове, uk | en — мова всіх листів цьому покупцеві. Що читає ваш покупець, знаєте лише ви, тому значення за замовчуванням немає. Зберігається в покупця з першим замовленням і далі не змінюється |
items |
array | обовʼязкове, від 1 до 50 рядків, хоча б один subscription |
items.*.external_id |
string | обовʼязкове, ≤ 255 — ідентифікатор товару в магазині (SKU) |
items.*.title |
string | обовʼязкове, ≤ 255 |
items.*.variant |
string | необовʼязкове, може бути null, ≤ 255 |
items.*.image_url |
string | обовʼязкове, url ≤ 2048 |
items.*.product_url |
string | обовʼязкове, url ≤ 2048 |
items.*.price |
integer | обовʼязкове, від 1 до 999999999 — копійки, до знижки |
items.*.quantity |
integer | обовʼязкове, від 1 до 9 |
items.*.mode |
string | обовʼязкове, one_time | subscription |
items.*.interval_value |
integer | обовʼязкове для subscription, від 1 до 365; для one_time відкидається |
items.*.interval_unit |
string | обовʼязкове для subscription, day | week; для one_time відкидається |
Інтервал у рядку one_time відкидається і повертається як null.
curl -X POST https://core.neocarts.com/v1/shop/orders/create \ -H "Authorization: Bearer nc_live_…" \ -H "Accept-Language: uk" \ -H "Content-Type: application/json" \ -d '{ "redirect_url": "https://shop.example.com/cart?neocarts=checkout", "locale": "uk", "items": [ { "external_id": "SKU-1", "title": "Brit Care Adult Large Breed", "variant": "12 кг", "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", "variant": "400 мл", "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 — рядки кошика з полями mode / interval_*, наприклад з NeocartsSubscription.getOrderItems(...)const response = await fetch('https://core.neocarts.com/v1/shop/orders/create', { method: 'POST', headers: { Authorization: 'Bearer nc_live_…', 'Accept-Language': 'uk', 'Content-Type': 'application/json', }, body: JSON.stringify({ redirect_url: 'https://shop.example.com/cart?neocarts=checkout', locale: 'uk', items, }),});const order = await response.json();// order.id — віджету; order.number — людямВідповідь — документ замовлення, той самий, який читає віджет (скорочено; повний опис полів — у Документі замовлення):
{ "id": "0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b", "number": "261004-48213", "shop_id": "…", "status": "draft", "redirect_url": "https://shop.example.com/cart?neocarts=checkout", "locale": "uk", "items": [ { "external_id": "SKU-1", "title": "Brit Care Adult Large Breed", "variant": "12 кг", "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", "variant": "400 мл", "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}Збережіть id для віджета; людям показуйте number. Знижка застосовується лише до рядків subscription і розраховується за правилами з Гроші та округлення.
| Статус | Коли |
|---|---|
201 |
замовлення відкрито — у відповіді документ замовлення |
401 |
ключа немає або він невідомий |
422 |
валідація — errors з ключами за буквальним шляхом поля, наприклад items.0.price або locale |
Що робити при помилці: 401 — зупиніться й перевірте ключ; 422 — виправте тіло за полем із errors; найчастіше це відсутній locale, ціна з дробовою частиною замість цілого числа копійок або кошик без жодного рядка subscription.
Замінити склад замовлення
Section titled “Замінити склад замовлення”Замінює кошик цілком і переоцінює його з тією знижкою, з якою замовлення було відкрито. Викликайте, коли покупець змінив кошик уже після того, як ваш сервер відкрив замовлення, але до початку оформлення.
Заголовки — ті самі, що й вище. {order} — id замовлення з відповіді на створення.
| Поле | Тип | Правила |
|---|---|---|
items |
array | обовʼязкове, від 1 до 50 рядків, хоча б один subscription; правила рядка — ті самі, що й при створенні |
curl -X PUT https://core.neocarts.com/v1/shop/orders/0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b/items \ -H "Authorization: Bearer nc_live_…" \ -H "Accept-Language: uk" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "external_id": "SKU-1", "title": "Brit Care Adult Large Breed", "variant": "12 кг", "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': 'uk', 'Content-Type': 'application/json', }, body: JSON.stringify({ items }),});
if (response.status === 409) { // замовлення вже не draft — відкрийте нове і передайте віджету новий id}const order = await response.json();Відповідь — оновлений документ замовлення, такий самий за формою, як при створенні.
| Статус | Коли |
|---|---|
200 |
склад замінено — у відповіді документ замовлення |
401 |
ключа немає або він невідомий |
404 |
невідоме замовлення або замовлення іншого магазину — {"message":"Not found."} |
409 |
замовлення вже не draft: оформлення почалося — {"message":"Товари замовлення, яке вже в оформленні, змінити не можна."}; або його скасовано — {"message":"Це замовлення скасовано."} |
422 |
валідація — errors з ключами за буквальним шляхом, наприклад items.0.price |
Що робити при помилці: 404 і 409 — відкрийте нове замовлення й передайте віджету новий id; 422 — виправте рядок, на який вказує errors.
Чому склад заморожується
Section titled “Чому склад заморожується”Щойно покупець натиснув «Перейти до оплати», замовлення стає pending_payment і його склад більше не змінюється — навіть якщо оплата не пройде. Так відкрита сторінка оплати зі старою сумою не купить інший кошик. Переходи — у Статусах.
Передати замовлення віджету
Section titled “Передати замовлення віджету”Сторінці магазину потрібен від сервера лише id замовлення. Поверніть його на сторінку й викличте NeocartsSubscription.open({ orderId }) — далі віджет сам веде покупця через контакти, доставку й оплату. Про результат ваш сервер дізнається з вебхуків. Як це зробити на сторінці — у Оформленні замовлення.