Going live

The pre-flight checklist before flipping from `brainerce_test_*` to `brainerce_*` in production. Skip steps at your own risk.

Before your first real customer transaction, walk this list end-to-end. Each item exists because someone shipped without it and paid for it later.

1. Keys and secrets

Rotated the test key. Make sure no brainerce_test_* key is hard-coded anywhere — search your repo and CI/CD secret stores for brainerce_test_ before deploy.
Issued a live key with minimum scopes. Don't ship a wildcard. Pick exactly the scopes the integration needs (Resource locations).
Stored the live key in a secret manager, not in .env checked into git. Doppler / 1Password / AWS SM / Vault — pick one.
Set an IP allowlist on the key (if your integration runs from fixed IPs). Lock down at the key, not the firewall — keys leak more than networks do.
Rotated BRAINERCE_API_KEY_PEPPER if you cloned env from staging. Live and staging must NOT share the pepper.
Customer JWT secret (CUSTOMER_JWT_SECRET) is distinct from staging.

2. Webhooks

Subscribed to the events you actually need — not all of them. Each event adds a delivery your endpoint has to handle correctly. See the webhook event catalogue.
Verification is in place — signature + replay window + constant-time compare. See Verify a webhook signature.
Idempotency on your side — store envelope.id and reject duplicates. Any non-2xx response is retried, not just 5xx: a 400, 404 or 409 from your handler is retried the full 5 attempts and counts toward the circuit breaker exactly like a timeout. If you want a delivery dropped rather than retried, answer 2xx and discard it yourself.
Reply fast. The dispatcher has a 10-second timeout. Reply with 2xx in under 2 seconds and queue the actual work async.
You have a plan for the circuit breaker, because self-healing is slow and lossy. Ten failed delivery attempts — roughly two consecutive failing events, since each event is tried 5 times — open the circuit. It half-opens an hour later and lets the next event (plus any arriving in the few seconds before its result lands) through as a probe: a 2xx resumes delivery, anything else re-opens it for another hour, and because failureCount is not reset, one failed probe is enough. Everything that happens meanwhile is never queued and cannot be replayed. Alert on circuitOpen: true (see §9) and treat it as a page, not a warning — waiting for the probe costs you an hour of events.
Tested with the dashboard "Send test event" button — confirmed signature verification passes against a real Brainerce-signed payload. Note this sends a fresh test event; there is no way to re-send a past delivery.

3. Idempotency on mutations

Every POST/PATCH/DELETE retry includes an Idempotency-Key. Otherwise a network blip can double-charge, double-ship, or double-cancel. See Idempotency.
Idempotency keys are deterministic per logical operation — same key for same retry, different key for different orders.
POST /v1/checkout/{id}/complete always carries a key. It is required there — without one the call is a 400, before the handler runs.
You have checked the unsupported list. Thirteen mutating /v1/* routes ignore the header silently, including POST /v1/orders/{id}/shipments/app-label, which buys a real shipping label and bills your carrier account on every retry. Read Idempotency → Routes that do NOT support it and guard those calls yourself.

4. Rate limits

You know your key's tier. A brainerce_* key is on the per-key tiers — FREE 60, PRO 500, GROWTH 2000, ENTERPRISE 10000 req/min. (The 100 / 500 / 1000 numbers are marketplace-app installation tiers and do not apply to an API key.)
You have accounted for the global per-IP ceiling on top of that — 60 req/min and 1000 req/hour per IP apply to every request regardless of tier, and some storefront routes cap far lower. See Rate limits.
You handle 429 Too Many Requests with the Retry-After header — don't hot-loop. Note X-RateLimit-Reset is seconds remaining, not a Unix timestamp.
Burst protection on your side — if a CSV import wakes up 10,000 jobs, batch them so you stay under your tier. There is no burst grace; the bucket rejects at exactly the limit.

5. Inventory + stock

Test-key inventory doesn't carry over. Verify your live products have real stock loaded — Brainerce defaults to TRACKED + 0 if you didn't set it.
Decided on trackingMode per product. TRACKED (default) blocks oversells; UNLIMITED accepts any order. Get this wrong and you either oversell or never sell.

6. Payments

Payment provider is in live mode — your payment app installation says mode: LIVE, not mode: TEST.
At least one full live transaction succeeded end-to-end before launch — your test, with a real card, $1 (you can refund).
Refund flow tested in live mode — provider-side refund settles, Brainerce-side PaymentRefund row reaches CAPTURED state.
Webhook on payment.failed writes to your CRM / alerts. Failed payments are the #1 silent failure mode in production.

7. Email

Email sending domain (DKIM/SPF) is verified in Brainerce email settings.
Transactional templates customized — order-confirmation, shipping-notification, password-reset have your branding (not the default).
From address is your domain, not [email protected].
Sent a test email to yourself for every event type your store will trigger.

8. Storefront

The sales channel's domain is your production domain. Set it under Channels → your channel → Settings. A LIVE channel matches the request Origin against this one field (host equality or a subdomain), so until it is right, browsers will get a 403 on every storefront call. Note a LIVE channel also requires an Origin header, which means SSR and Route Handlers cannot call it — see Rules.
CSP headers in your storefront allow Brainerce + your payment provider domains. A strict CSP blocks Stripe/PayPal iframes silently. If product descriptions use video embeds, also add https://www.youtube.com, https://www.youtube-nocookie.com, and https://player.vimeo.com to frame-src, or the embeds render blank.
Cookie domain is the production domain (not localhost or staging).
Custom domain SSL is provisioned and HSTS is set — Brainerce requires HTTPS on webhookUrl and OAuth callbacks.

9. Observability

Logs from your integration record the endpoint, and on errors the timestamp and path from the error body. There is no request-id response header — neither X-Request-Id nor X-Brainerce-Request-Id is set by the API, so generate your own correlation id client-side and log it alongside those two fields. That is what lets support find the request.
You have an alert on 5xx rate from Brainerce. If your integration starts seeing 5%+ 5xx, something is wrong (yours, ours, or upstream).
Webhook circuit-breaker state is monitored. If your endpoint opens the circuit, you stop receiving events — silently. Check GET /stores/{storeId}/webhook-subscriptions/{id} periodically for circuitOpen: true and alert.
A dashboard chart of API key usage exists (your side) — sudden spikes/drops are the first sign of a compromised key or a broken cron.

Customer data export endpoint wired — for "deliver my data" requests under GDPR / CCPA. GET /api/v1/customers/{id} covers most of it.
Customer deletion endpoint wired — DELETE /api/v1/customers/{id} cascades to orders. Verify before live customer requests come in.
Marketing consent flag is respected — customer.acceptsMarketing: false should never receive a marketing email.
Privacy policy + terms-of-service URLs in store settings point at live, signed-off legal pages.

11. Versioning

You're calling /api/v1/* paths, not internal /api/{module} ones. Internal paths can change without notice; /api/v1/* carries the versioning guarantee.
Someone owns reading the Changelog before each SDK bump. There is no deprecation response header to automate against — X-Brainerce-Deprecation is not emitted — so the changelog and the dashboard banner are the whole early-warning system.

12. Rollback plan

You can roll your storefront back to the previous Brainerce SDK version within 5 minutes — pinned to a major in package.json, prior version cached.
You can disable a webhook subscription without redeploying — DELETE the subscription via the API, or toggle it in the dashboard.
You can revoke a leaked API key in under 60 seconds — practiced once before launch.

13. Day 1 verification

After the first hour of live traffic, confirm:

First real order.created arrived at your webhook and was processed
First real payment.succeeded settled in the payment-provider dashboard
New shoppers are reaching your CRM. customer.created fires for a merchant-created customer and for a storefront, email-verified or OAuth signup. It does not fire for a guest checkout — those shoppers arrive on order.created / checkout.completed, which carry the enriched customer. Confirm your handler is an upsert keyed on customerId: a guest who later registers produces a customer.created for a customer you already have. See the event catalogue.
Your 5xx rate is < 1%
Your webhook delivery success rate (in Brainerce dashboard) is > 99%

If any of these are red, your launch is degraded — fix before pushing more traffic.

Quickstart — first authenticated request
Authentication — API keys, scopes, sandbox
Idempotency — the retry-safe pattern
Rate limits — your tier + recommended client behavior
Verify a webhook signature — required reading
Resource locations — which namespace each resource lives in

On this page