Environments
Use the correct host for the key. Sandbox resources do not exist in production.
Authentication
Authorization: Bearer, not X-Api-Key. Keep secret keys server-side.
Public checkout routes under /pay/{slug} do not take a merchant secret key.
Agent provisioning
POST /public/v1/claimables is public and accepts optional ref, accountName
and email. It returns apiKeySecret, publishableKey, tenantSlug, productId,
claimUrl and expiresAt. Email is an unverified contact, never an identity.
With the claim-email update, providing an address queues a transactional message
with the link and deadline, at most once per address every 24 hours. A 201
confirms provisioning, not email delivery. Always preserve the returned claim URL.
Read agent onboarding for questions, credentials and
human handoff. Do not blindly repeat this POST after a lost response: the account
may already exist.
IDs
Every id says what it is by its prefix:cus_ customer, prod_ product, inv_ invoice, pay_ payment, sub_ subscription, coup_ coupon, re_ refund, we_ webhook endpoint, acct_ account. After the prefix come 22 characters (0-9A-Za-z), and case matters.
- Store an id as text, exactly as it came. Do not lowercase it.
- An id of another kind in the wrong place (a
cus_where aninv_goes) answers400, naming the prefix it expected. - Old ids, a bare UUID, are still accepted as input for a while. Responses and webhooks already use the new form.
Idempotency
Authenticated mutations require anIdempotency-Key. Use a stable, unique value
for each operation and reuse it only when retrying that same operation.
400 idempotency_key_required; reusing a key with a
different body returns 409 idempotency_key_reused.
Public bootstrap routes have their own requirements. Do not assume every public
route needs a merchant key or uses the same request shape.
Responses and errors
Collection reads return envelopes such as{"products": [...]} .
Resource creation may return a composite response: product creation returns
both product and a draft version. Check the endpoint contract instead of
assuming every resource is at the root.
Errors may use the handler envelope (error_code, message, errors,
tracer_id) or the middleware envelope (error.code, error.message,
error.request_id). Preserve diagnostic IDs when reporting a problem.