Skip to content

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.

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

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.

PUT/v1/shop/products/{external_id}Bearer: shop API key

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.

Terminal window
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"
}'

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.

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.

PUT/v1/shop/products/{external_id}/priceBearer: shop API key

Headers — the same as above.

Field Type Rules
price integer required, 1 to 999999999 — kopecks, before the subscriber discount. 259000 means 2 590,00 ₴
Terminal window
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}'
{
"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.

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