Товари
Товар у Neocarts належить магазину: Neocarts зберігає ту картку, яку йому надіслали востаннє, і ніколи не вигадує власної. Картка не містить ціни: ціна живе на оформленому замовленні та на підписці, яка далі списує, а не в каталозі, на який обидва посилаються.
Контракт товару
Section titled “Контракт товару”| Поле | Тип | Правила |
|---|---|---|
external_id |
string ≤ 255 | власний ідентифікатор магазину на рівні варіанта (SKU). Незмінний — новий ідентифікатор означає новий товар. Не може містити / |
title |
string ≤ 255 | обовʼязкове |
variant |
string ≤ 255 | необовʼязкове, може бути null — «12 кг», «синій»; єдине необовʼязкове поле |
image_url |
url ≤ 2048 | обовʼязкове |
product_url |
url ≤ 2048 | обовʼязкове |
Товар створюється, коли Neocarts уперше бачить його external_id для цього магазину — у кошику або через ендпоінт нижче, — і оновлюється при кожній наступній появі. Останній запис перемагає. Кожен рядок кошика в POST /v1/shop/orders/create теж є записом у каталог (окрім ціни).
Оновити картку товару
Section titled “Оновити картку товару”Надішліть поточний стан товару — зазвичай із хука «товар збережено» в адмінці вашої платформи, щоб назва і зображення, які бачить передплатник, залишалися актуальними.
Заголовки — як описано в Автентифікації: Authorization: Bearer nc_live_…, Accept-Language, Content-Type: application/json.
| Поле | Тип | Правила |
|---|---|---|
title |
string | обовʼязкове, ≤ 255 |
image_url |
string | обовʼязкове, url ≤ 2048 |
product_url |
string | обовʼязкове, url ≤ 2048 |
variant |
string | необовʼязкове, може бути null, ≤ 255 — відсутнє означає порожнє |
Тіло — це весь товар, а не патч: кожен запит замінює кожне поле, тож щоразу надсилайте все, що маєте.
curl -X PUT https://core.neocarts.com/v1/shop/products/SKU-1 \ -H "Authorization: Bearer nc_live_…" \ -H "Accept-Language: uk" \ -H "Content-Type: application/json" \ -d '{ "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" }'const response = await fetch('https://core.neocarts.com/v1/shop/products/SKU-1', { method: 'PUT', headers: { Authorization: 'Bearer nc_live_…', 'Accept-Language': 'uk', 'Content-Type': 'application/json', }, body: JSON.stringify({ 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', }),});const product = await response.json();Відповідь — товар, як його збережено:
{ "id": "0198c2a1-7b3e-7f10-9a2d-3c4e5f6a7b8c", "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", "updated_at": "2026-09-04T10:15:00+00:00"}| Статус | Коли |
|---|---|
201 |
цей external_id побачено для магазину вперше — товар створено |
200 |
товар оновлено |
401 |
ключа немає або він невідомий |
422 |
валідація — errors з ключами за назвами полів |
Що робити при помилці: 401 — зупиніться й перевірте ключ; 422 — виправте тіло, errors називає поле. Докладніше — у Помилках.
Переоцінити підписки
Section titled “Переоцінити підписки”Змінює ціну в кожній активній і призупиненій підписці на товар. Скасованих підписок це не стосується: їх повторне увімкнення — окреме рішення, а ціну видно на сторінці підписки. Кожна підписка зберігає власну знижку — цей запит задає ціну, до якої ця знижка застосовується.
Заголовки — ті самі, що й вище.
| Поле | Тип | Правила |
|---|---|---|
price |
integer | обовʼязкове, від 1 до 999999999 — копійки, до знижки передплатника. 259000 означає 2 590,00 ₴ |
curl -X PUT https://core.neocarts.com/v1/shop/products/SKU-1/price \ -H "Authorization: Bearer nc_live_…" \ -H "Accept-Language: uk" \ -H "Content-Type: application/json" \ -d '{"price": 259000}'const response = await fetch('https://core.neocarts.com/v1/shop/products/SKU-1/price', { method: 'PUT', headers: { Authorization: 'Bearer nc_live_…', 'Accept-Language': 'uk', 'Content-Type': 'application/json', }, body: JSON.stringify({ price: 259000 }),});const { updated } = await response.json();{ "updated": 12}| Статус | Коли |
|---|---|
200 |
виконано — updated показує, скільки підписок тепер списують нову ціну (0 — нормальна відповідь) |
401 |
ключа немає або він невідомий |
404 |
у цьому магазині немає такого товару — {"message":"Not found."} |
422 |
валідація — errors з ключами за назвами полів |
Нова ціна діє з наступного списання кожної підписки; замовлення, що вже виставлене й чекає на оплату, не переоцінюється — під час наступної спроби списання його скасовують і створюють нове. Кожен клієнт, якого це стосується, отримує лист «Ціна у вашій підписці змінилася» з датою наступного списання — див. Листи.
Що робити при помилці: 404 — перевірте external_id: товар зʼявляється в Neocarts лише після першого кошика або PUT картки; 422 — ціна має бути цілим числом копійок від 1 до 999999999.
Які товари можна передплачувати
Section titled “Які товари можна передплачувати”Це рішення магазину. Neocarts не зберігає жодного прапорця: саме ваш бік не повинен класти в кошик із mode: subscription товар, на який не можна підписатися. Якщо товар не підлягає передплаті, не показуйте для нього вибір «підписка» і не вставляйте для нього кнопку підписки.
Зняття товару з продажу
Section titled “Зняття товару з продажу”Зняти товар із продажу — завдання магазину: просто перестаньте класти його в кошики. Окремого ендпоінта для цього немає. Окрім цього, на сторінці товару в панелі магазину всі підписки на нього можна призупинити або скасувати разом, із причиною, яка залишається на підписці покупця (при скасуванні — product_discontinued, див. Довідник значень).