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:
“Bearer: shop API key” means the header described on this page. Successful requests are not rate-limited.
The key
Section titled “The key”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, not403— Neocarts does not confirm that the object exists at all.
Headers on every request
Section titled “Headers on every request”| 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 |
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"}'const NEOCARTS_KEY = 'nc_live_…'; // server only, never in the browser
const response = await fetch('https://core.neocarts.com/v1/shop/products/SKU-1', { method: 'PUT', headers: { Authorization: `Bearer ${NEOCARTS_KEY}`, '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/i/brit.jpg', product_url: 'https://shop.example.com/p/brit', }),});401 and 429 answers
Section titled “401 and 429 answers”| 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. |
No CORS
Section titled “No CORS”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.
What to do on error
Section titled “What to do on error”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.