Products
A product in Neocarts is the merchant’s: Neocarts stores the card it was last sent and never invents one. The card carries no price: the price lives on the placed order and on the subscription that keeps charging, not in the catalogue both point at.
Product contract
Section titled “Product contract”| Field | Type | Rules |
|---|---|---|
external_id |
string ≤ 255 | the shop’s own id, at variant level (a SKU). Immutable — a new id is a new product. Must not contain / |
title |
string ≤ 255 | required |
variant |
string ≤ 255 | optional, nullable — “12 kg”, “blue”; the only optional field |
image_url |
url ≤ 2048 | required |
product_url |
url ≤ 2048 | required |
A product is created the first time Neocarts sees its external_id for the shop — in a cart or through the endpoint below — and updated on every later sight. The last write wins. Every cart line in POST /v1/shop/orders/create is also a catalogue write (except for the price).
Update a product card
Section titled “Update a product card”Push the product’s current state — typically from the “product saved” hook of your platform’s admin, so the name and the picture a subscriber sees stay current.
Headers as described in Authentication: Authorization: Bearer nc_live_…, Accept-Language, Content-Type: application/json.
| Field | Type | Rules |
|---|---|---|
title |
string | required, ≤ 255 |
image_url |
string | required, url ≤ 2048 |
product_url |
string | required, url ≤ 2048 |
variant |
string | optional, nullable, ≤ 255 — absent means empty |
The body is the whole product, not a patch: every push replaces every field, so send what you have every time.
curl -X PUT https://core.neocarts.com/v1/shop/products/SKU-1 \ -H "Authorization: Bearer nc_live_…" \ -H "Accept-Language: en" \ -H "Content-Type: application/json" \ -d '{ "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" }'const response = await fetch('https://core.neocarts.com/v1/shop/products/SKU-1', { method: 'PUT', headers: { Authorization: 'Bearer nc_live_…', 'Accept-Language': 'en', 'Content-Type': 'application/json', }, body: JSON.stringify({ 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', }),});const product = await response.json();Response — the product as stored:
{ "id": "0198c2a1-7b3e-7f10-9a2d-3c4e5f6a7b8c", "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", "updated_at": "2026-09-04T10:15:00+00:00"}| Status | When |
|---|---|
201 |
this external_id was seen for the shop for the first time — product created |
200 |
product updated |
401 |
no or unknown key |
422 |
validation — errors keyed by field |
What to do on error: 401 — stop and check the key; 422 — fix the body, errors names the field. More in Errors.
Reprice subscriptions
Section titled “Reprice subscriptions”Changes the price in every active and paused subscription of the product. Cancelled subscriptions are left alone: reactivating one is a decision of its own, and the price is visible on the subscription’s page. Each subscription keeps its own discount — this request sets the price that discount applies to.
Headers — the same as above.
| Field | Type | Rules |
|---|---|---|
price |
integer | required, 1 to 999999999 — kopecks, before the subscriber discount. 259000 means 2 590,00 ₴ |
curl -X PUT https://core.neocarts.com/v1/shop/products/SKU-1/price \ -H "Authorization: Bearer nc_live_…" \ -H "Accept-Language: en" \ -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': 'en', 'Content-Type': 'application/json', }, body: JSON.stringify({ price: 259000 }),});const { updated } = await response.json();{ "updated": 12}| Status | When |
|---|---|
200 |
done — updated is how many subscriptions now charge the new price (0 is a normal answer) |
401 |
no or unknown key |
404 |
no such product in this shop — {"message":"Not found."} |
422 |
validation — errors keyed by field |
The new price applies from each subscription’s next charge; an order already issued and awaiting payment is not repriced — at the next charge attempt it is cancelled and a new one is created. Every affected customer receives the “The price in your subscription changed” email naming the next charge date — see Emails.
What to do on error: 404 — check the external_id: a product exists in Neocarts only after its first cart or a PUT of its card; 422 — the price has to be an integer number of kopecks, 1 to 999999999.
Which products are subscribable
Section titled “Which products are subscribable”That is the shop’s decision. Neocarts stores no flag: your side must not put a product that cannot be subscribed to into a cart with mode: subscription. If a product is not subscribable, do not offer a “subscription” choice for it and do not embed the subscribe button for it.
Taking a product off the market
Section titled “Taking a product off the market”Taking a product off the market is the shop’s job: stop putting it into carts. There is no endpoint for it. Beyond that, the product’s page in the shop panel lets every subscription on it be paused or cancelled at once, with a reason that stays on the shopper’s subscription (product_discontinued for a cancellation, see Enums).