Skip to content

Authentication

The Shop API is the server half of the integration. Your server (or the plugin for your platform) calls https://core.neocarts.com/v1/shop/* and identifies itself with the shop’s key. The key is the shop’s identity: no request carries a shop_id in its body, and an order or a product always belongs to the shop whose key arrived.

Every endpoint in this section is labelled like this:

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

“Bearer: shop API key” means the header described on this page. Successful requests are not rate-limited.

A key looks like nc_live_ followed by 40 characters.

  • Where it comes from. The shop’s owner generates it in the shop panel, Settings → Integration, or a Neocarts admin does from the shop’s page. It is shown once: a lost key can only be replaced with a new one.
  • One live key per shop. Regenerating retires the previous key immediately, with no grace period: the integration fails until the new key is put into it. Plan the swap.
  • The key identifies the shop. Another shop’s order or product answers 404, not 403 — Neocarts does not confirm that the object exists at all.
Header Value
Authorization Bearer nc_live_… — required
Accept-Language uk or en — the language of messages and validation errors, field names inside them included. Without the header the server answers in English.
Content-Type application/json for requests with a body
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/i/brit.jpg","product_url":"https://shop.example.com/p/brit"}'
Status When
401 the key is missing or unknown — both cases get the same {"message":"Unauthenticated."}
429 60 failed key attempts were made from one IP address within a minute. For the rest of that minute every request from the address, the right key included, answers 429. A valid key is never rate-limited on its own — only failures count.

The Shop API sends no CORS headers and is server-to-server by design. A browser holding a shop key is exactly the leak this scheme exists to close. Never ship the key to the page, to the catalogue’s JavaScript or to a theme setting.

The shop’s page runs the widget, which needs no key: all it needs is the order id, which your server obtains through the Shop API and hands to the page.

  • 401 — stop and tell the shop’s administrator: the key is missing, wrong or already regenerated. Retrying will not help.
  • 429 — check the key and wait until the minute is over; requests go through afterwards.

The full list of statuses and actions is in Errors.