NeroCart Developers TR

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.

O

Orders and invoices

Read orders, follow their state, ship them and fetch their invoices.

P

Products and stock

Manage products, variants, categories and pictures; keep stock in step across locations.

C

Customers

Keep customer records and groups in sync with your CRM.

W

Webhooks

Receive more than 50 events — new orders, payments, shipments, stock — at once and signed.

A

Apps (OAuth)

OAuth 2.0 with PKCE for apps that many stores install.

S

Storefront API

A public API, no key needed, for the catalogue, the cart and checkout.

Get started

  1. 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.
  2. Copy it. The key (nck_…) is shown once; keep it in your program's secret settings.
  3. 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.

FeatureHow it works
Least privilegeA 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.
StorageA 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.
ExpiryA key can be made to stop by itself after 30 days, 90 days or a year.
IP allowlistA key can be accepted only from given IP addresses or CIDR ranges (IPv4/IPv6).
Store bindingIn an account with several stores a key can be bound to one.
AuditLast use is recorded; making, revoking and deleting a key is written to the activity log.
AppsApps 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:

  1. 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).
  2. Revoke the leaked key in Settings › API keys if it is not revoked already, then delete it.
  3. 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.
  4. 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.
  5. 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": { … } }
HeaderMeaning
X-NeroCart-Signaturet=<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-EventThe event's name, e.g. order.paid
X-NeroCart-Event-IdThe event's id: process an event that arrives twice once.
X-NeroCart-Event-VersionThe body's schema version (v).
X-NeroCart-Delivery-IdThis 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

Node.js
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)));
}
PHP
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;
}
Python
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.

StatusWhen
400A missing or wrong field (validation); details.field names it.
401No key, a wrong, revoked or expired one, or a call from an address the key does not allow.
403The key has no access to this area.
404No such record, or not this store's.
409A state conflict (e.g. the same request is still running).
422The same Idempotency-Key was used with a different request.
429Rate 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

ScopeLimit
Per API key600 requests a minute (bursts of 120)
Per IP address1,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.

DateChange
11 Nov 2026Key checksum: new keys end in a seven-character CRC32 checksum (nck_<8>_<39>); keys made before keep working.
10 Nov 2026Key areas: Inventory write now includes warehouse locations (locations.write), Products write includes deleting media (media.delete).
10 Nov 2026Carrier 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 2026Developer guide and the full API reference published; the admin API (/api/v1/admin) is in the reference.
9 Nov 2026NeroCart names: webhook headers are X-NeroCart-*, new keys start nck_.
9 Nov 2026Key security: read/write access over 21 areas, expiry, IP allowlist, renewal, deleting revoked and expired keys.
9 Nov 2026Idempotency-Key on every admin write; a repeated request gets the first answer.
9 Nov 2026Pagination: a Link header (RFC 8288) and meta.has_more on every list.
9 Nov 2026Request log: each key's latest calls, results and timings in the panel (30 days).
9 Nov 2026Webhook test delivery: POST /api/v1/admin/x/webhooks/endpoints/{id}/test and Send test in the panel.
9 Nov 2026Developer test stores, a status page and a Postman collection.
9 Nov 2026Leaked key protection: nck_ keys GitHub finds in public are revoked automatically.

Resources