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.
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.