Build with NeroCart
Connect a store to accounting, ERP, shipping, marketplaces and your own software. A versioned REST API, signed webhooks and OAuth 2.0 apps make integrations that are safe, predictable and built to last.
Orders and invoices
Read orders, follow their state, ship them and fetch their invoices.
Products and stock
Manage products, variants, categories and pictures; keep stock in step across locations.
Customers
Keep customer records and groups in sync with your CRM.
Webhooks
Receive more than 50 events — new orders, payments, shipments, stock — at once and signed.
Apps (OAuth)
OAuth 2.0 with PKCE for apps that many stores install.
Storefront API
A public API, no key needed, for the catalogue, the cart and checkout.
Get started
- Make a key. In the store panel open Settings › Advanced › API keys, press New key, name it and choose Read, Write or Read and write for each area.
- Copy it. The key (
nck_…) is shown once; keep it in your program's secret settings. - Send the first request. Every store answers the API on its own domain:
curl https://yourstore.com/api/v1/admin/orders?limit=10 \ -H "Authorization: Bearer nck_XXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
{
"data": [ { "id": 17217, "number": "GC-000003", "status": "confirmed", "total": { "amount_minor": 65000, "currency": "TRY" }, … } ],
"meta": { "total": 128, "limit": 10, "offset": 0, "page": 1, "total_pages": 13, "has_more": true }
}
Amounts are always whole numbers of the currency's smallest unit (65000 = 650.00 TRY); never decimals.
Test store
To try your integration without touching a live store, NeroCart opens a developer test store for you: payments are always in test mode (no real money, test orders only, never invoiced or shipped) and its pages are closed to search engines. The API, webhooks and panel are exactly the live store's. Write to us to get one.
Authentication and security
The admin API (/api/v1/admin) needs Authorization: Bearer <key> on every call. The storefront API (/api/v1/store) needs none.
| Feature | How it works |
|---|---|
| Least privilege | A key reaches only the areas chosen for it: orders, products, stock, customers, discounts and prices, shipping, reports. Refunds and the store's settings are never open to a key. |
| Storage | A key is shown only when it is made; only its SHA-256 is kept. The nck_ prefix and the key's last seven characters, a CRC32 checksum, let secret scanners recognise a leaked key without false alarms. |
| Expiry | A key can be made to stop by itself after 30 days, 90 days or a year. |
| IP allowlist | A key can be accepted only from given IP addresses or CIDR ranges (IPv4/IPv6). |
| Store binding | In an account with several stores a key can be bound to one. |
| Audit | Last use is recorded; making, revoking and deleting a key is written to the activity log. |
| Apps | Apps installed by many stores use the OAuth 2.0 authorization code flow with PKCE (RFC 7636); the merchant sees the permissions on a consent screen. |
If a key leaks
NeroCart is a GitHub secret scanning partner. When a NeroCart API key (nck_…) is pushed to a public GitHub repository, gist, issue or package, GitHub reports it to us and we revoke the key at once; every call made with it is refused from that moment. The revocation is written to the store's audit log (Settings › Audit log).
What to do, whether GitHub found the key or you did:
- Make a new key in Settings › API keys, with only the areas your program needs, and put it in your program's secret settings (an environment variable or a secrets manager, never in code).
- Revoke the leaked key in Settings › API keys if it is not revoked already, then delete it.
- Remove the key from the code and its history. Deleting the file is not enough: rewrite the history (for example with
git filter-repo) or treat the repository as exposed. A revoked key cannot be used, but keep secrets out of repositories. - Check what the key did. Each key's request log (Settings › API keys › the key) shows its calls of the last 30 days; the audit log shows what was changed.
- Narrow future keys: give each program its own key, the fewest areas it needs, an expiry date and, where you can, an IP allowlist.
Found a key that is not yours, or need help? Write to info@nerocart.com.
Webhooks
Add an address in the panel under Settings › Advanced › Developer and choose the events. Each event is POSTed as JSON:
{ "id": "…", "name": "order.paid", "v": 1, "at": "2026-11-09T10:53:37Z",
"aggregate_type": "order", "aggregate_id": 17217, "data": { … } }
| Header | Meaning |
|---|---|
X-NeroCart-Signature | t=<unix>,v1=<HMAC-SHA256> over "<t>.<body>" with the endpoint's secret. While a secret is rotated a second v1= signed with the old one follows; accept when any matches. |
X-NeroCart-Event | The event's name, e.g. order.paid |
X-NeroCart-Event-Id | The event's id: process an event that arrives twice once. |
X-NeroCart-Event-Version | The body's schema version (v). |
X-NeroCart-Delivery-Id | This delivery's record; the same on every retry. |
An answer other than 2xx, or a timeout, is retried 12 times with growing intervals; the panel lists every delivery with a Resend button.
Verifying the signature
import crypto from "node:crypto";
export function verify(header, rawBody, secret, toleranceSec = 300) {
const parts = header.split(",").map((p) => p.trim().split("="));
const t = parts.find(([k]) => k === "t")?.[1];
const sigs = parts.filter(([k]) => k === "v1").map(([, v]) => v);
if (!t || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
const want = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return sigs.some((s) => s.length === want.length &&
crypto.timingSafeEqual(Buffer.from(s), Buffer.from(want)));
}
function nerocart_verify(string $header, string $rawBody, string $secret, int $tolerance = 300): bool {
$t = null; $sigs = [];
foreach (explode(',', $header) as $part) {
[$k, $v] = array_pad(explode('=', trim($part), 2), 2, '');
if ($k === 't') $t = $v; elseif ($k === 'v1') $sigs[] = $v;
}
if ($t === null || abs(time() - (int)$t) > $tolerance) return false;
$want = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
foreach ($sigs as $s) if (hash_equals($want, $s)) return true;
return false;
}
import hashlib, hmac, time
def verify(header: str, raw_body: bytes, secret: str, tolerance: int = 300) -> bool:
parts = [p.strip().split("=", 1) for p in header.split(",")]
t = next((v for k, v in parts if k == "t"), None)
sigs = [v for k, v in parts if k == "v1"]
if t is None or abs(time.time() - int(t)) > tolerance:
return False
want = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(want, s) for s in sigs)
Events
order.created, order.paid, order.shipped, order.delivered, order.cancelled, order.refunded, order.edited, fulfillment.tracking_updated, fulfillment.delivered, return.requested, return.closed, product.created, product.updated, product.deleted, price.changed, inventory.level_changed, cart.abandoned, category.updated, collection.updated, promotion.changed and more — the full list and each event's body schema are in the API reference.
Conventions
Answers and errors
A success is {"data": …}, an error {"error": {"code", "message", "details"}}. Every answer carries X-Request-Id; quote it when asking for help.
| Status | When |
|---|---|
400 | A missing or wrong field (validation); details.field names it. |
401 | No key, a wrong, revoked or expired one, or a call from an address the key does not allow. |
403 | The key has no access to this area. |
404 | No such record, or not this store's. |
409 | A state conflict (e.g. the same request is still running). |
422 | The same Idempotency-Key was used with a different request. |
429 | Rate limited; wait Retry-After seconds and retry. |
Pagination
Lists take limit (at most 200, 50 by default) with offset or page. The answer's meta gives the total and has_more; the Link header (RFC 8288) names the first, previous, next and last windows. Follow rel="next" until it is gone:
Link: </api/v1/admin/orders?limit=50&offset=0>; rel="first", </api/v1/admin/orders?limit=50&offset=100>; rel="next", </api/v1/admin/orders?limit=50&offset=1250>; rel="last"
Repeated requests (Idempotency-Key)
Give every POST, PUT, PATCH and DELETE a unique Idempotency-Key. If the connection drops and the request is sent again, the first answer comes back as it was (Idempotent-Replayed: true) and nothing happens twice. Keys are kept for 24 hours.
curl -X POST https://yourstore.com/api/v1/admin/products \
-H "Authorization: Bearer nck_…" -H "Idempotency-Key: 6f1c2b7e-product-import-001" \
-H "Content-Type: application/json" -d '{"title":"Green tea 100 g", …}'
Rate limits
| Scope | Limit |
|---|---|
| Per API key | 600 requests a minute (bursts of 120) |
| Per IP address | 1,200 requests a minute (bursts of 300) |
Every answer carries RateLimit-Limit and RateLimit-Remaining; over the limit you get 429 with Retry-After.
Versions
The API lives under /api/v1 and only grows within it: no field or route is removed or changes meaning, a rule an automatic contract check enforces on every release. A breaking change comes only with a new version (/api/v2) and an announced transition period.
Postman and code generation
The whole API is an OpenAPI 3 contract; client code and a test collection are generated from it.
Postman
In Postman choose Import › Link and give https://nerocart.com/developers/postman.json. Set the collection's baseUrl to your store's address and apiKey to your key.
TypeScript / JavaScript
npx openapi-typescript https://nerocart.com/doc -o nerocart.d.ts npm i openapi-fetch
import createClient from "openapi-fetch";
import type { paths } from "./nerocart";
const api = createClient<paths>({ baseUrl: "https://yourstore.com", headers: { Authorization: `Bearer ${process.env.NEROCART_KEY}` } });
const { data } = await api.GET("/api/v1/admin/orders", { params: { query: { limit: 50 } } });
PHP, Python, Java, C#, Go
npx @openapitools/openapi-generator-cli generate -i https://nerocart.com/doc -g php -o nerocart-php # -g python | java | csharp | go
Changelog
Every change to the API is listed here with its date. Within /api/v1 changes only add; existing integrations keep working. Live state: status page.
| Date | Change |
|---|---|
| 11 Nov 2026 | Key checksum: new keys end in a seven-character CRC32 checksum (nck_<8>_<39>); keys made before keep working. |
| 10 Nov 2026 | Key areas: Inventory write now includes warehouse locations (locations.write), Products write includes deleting media (media.delete). |
| 10 Nov 2026 | Carrier identity lookup: GET /api/v1/admin/shipping/carrier-profiles/lookup finds a carrier's legal name, tax number and tax office; invoices use the carrier profile. |
| 9 Nov 2026 | Developer guide and the full API reference published; the admin API (/api/v1/admin) is in the reference. |
| 9 Nov 2026 | NeroCart names: webhook headers are X-NeroCart-*, new keys start nck_. |
| 9 Nov 2026 | Key security: read/write access over 21 areas, expiry, IP allowlist, renewal, deleting revoked and expired keys. |
| 9 Nov 2026 | Idempotency-Key on every admin write; a repeated request gets the first answer. |
| 9 Nov 2026 | Pagination: a Link header (RFC 8288) and meta.has_more on every list. |
| 9 Nov 2026 | Request log: each key's latest calls, results and timings in the panel (30 days). |
| 9 Nov 2026 | Webhook test delivery: POST /api/v1/admin/x/webhooks/endpoints/{id}/test and Send test in the panel. |
| 9 Nov 2026 | Developer test stores, a status page and a Postman collection. |
| 9 Nov 2026 | Leaked key protection: nck_ keys GitHub finds in public are revoked automatically. |