Reliability contract

Same key, same payload → the stored response, with its original status code, plus X-Idempotent-Replayed: true. Stored responses replay for 24 hours.

Same key, different payload → 422 idempotency_key_reuse. Answering with the first request's response would silently discard the second — an order the merchant believes was placed and that never existed. We would rather fail loudly.

The payload fingerprint is canonicalized first: object key order does not matter (your SDK is free to re-serialize a retry), array order does.

The loser gets 409 idempotency_conflict with Retry-After: 1. Retry and you get the winner's response.

An in-flight claim expires after 15 minutes, so a handler that died mid-flight cannot block a legitimate retry for the rest of the day.

On a money operation the claim holds for the key's full 24 hours instead. A request that ended without its answer being recorded may already have charged, and running it again under the same key could charge twice, so a same-key retry keeps getting 409 idempotency_conflict. Check GET /v1/orders before placing it again with a new key.

Validation failures and declined cards free the slot: fix the request and retry with the same key. An outcome that did touch money and then reversed it (charged, then refunded) is sealed — it replays as-is, and placing the order for real requires a new key.

On an operation that charges or refunds — an order, a batch, an item, a shipping or address change, a cancellation — a key the ledger cannot check is answered 503 idempotency_unavailable with a Retry-After, and nothing runs or is charged. Retry with the same key.

The cursor holds the position of the last row you were actually given — its timestamp and row id — and the next page starts one row past it. Rows created while you page do not shift the ones you already read — the failure mode of OFFSET paging, where a single insert makes you miss a record entirely.

This holds for rows written in the same instant, too. Every keyset list is ordered by its timestamp and then by row id, so a batch write — 50 orders from one /orders/bulk call — cannot leave a page boundary sitting inside a group of rows whose relative order is undefined. The product catalog is not a table: its cursor names the last row's place in the catalog's own order, its SKU and the SKU of the row after it, so a product added or removed elsewhere in the catalog moves nothing you have read, and if the last row you were given leaves, the walk resumes at the row that followed it. Only if both leave between two requests does it fall back to the old place.

We fetch one row beyond your page to decide it — never from a page that came back short — and next_cursor is null exactly when it is false. Loop on it; do not guess from the item count. The row that said there was more can be deleted before you ask for it (a webhook or an asset you remove mid-walk), so a page after has_more: true can come back empty; the walk still ends at the first has_more: false.

A cursor is bound to the list that returned it, to your account, to the key's mode (test or live) and to the filters it was returned under — and an order's events cursor to that order. One that was altered, that came from another list, account or mode, or that is sent with other filters (a status dropped, a search changed), is refused with 400 validation_error and a details.reason, never answered with someone else's page or a wrong one. Pass it back exactly as you received it.

Above 100 it clamps to 100; abc, Infinity, 0 and an empty cursor fall back to the default, -5 to 1, and 2.7 to 2. No 500s from a malformed query string.

t=<unix-seconds>,v1=<hex> where the HMAC-SHA256 covers <t>.<raw body>. A body-only signature is valid forever — anyone who ever observes one delivery could replay it months later. Verify v2 and reject a timestamp drifting more than 300 seconds from your clock.

The original sha256=<hex> body-only header still ships on every request, so verifiers written against the older docs do not break. New integrations should verify v2.

A retry after a long backoff carries a fresh t describing when that request was sent — it will not fail your clock-drift check for being old.

POST /v1/webhooks/{id}/rotate-secret needs an API key with webhooks:manage — not a browser session. When a signing secret leaks, the clock is running, and a remedy that requires a human to log in is a remedy your integration cannot reach. Close the overlap early with DELETE on the same path.

Rotate and we sign each delivery with both the new and the outgoing secret — one v1= per secret in the same X-PS-Signature-V2 header. Deploy the new secret whenever you like inside the window; nothing 401s in between.

This is the one place a naive verifier breaks. Parsing the header into a map (Object.fromEntries / dict(...)) keeps only the last duplicate key. We emit the active secret first and the outgoing one last precisely so that a map-based verifier still holding the old secret keeps verifying for the whole window — but collect every v1 and accept if any matches, as the snippet above does.

Default grace is 24 hours, and the maximum you can request is 168 hours. Expiry is evaluated at signing time, not by a cleanup job — an expired secret stops being honored the moment it expires, never “whenever the sweeper next runs”.

The single-valued X-PS-Signature can only hold one MAC, so during a rotation it is accompanied by X-PS-Signature-Previous.

One logical event keeps one id across all retries and across a later manual redelivery. Dedupe on it and at-least-once delivery becomes effectively exactly-once for your side effects.

Deliveries run from a durable queue, and the waits between attempts are 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, then 6 hours, so an endpoint that is down for a deploy still receives everything it missed. We retry 5xx, timeouts, 408, and 429 — the responses that ask us to come back. Any other 4xx means the payload or the endpoint is wrong and a retry would fail identically, so we stop and notify you instead of hammering a broken endpoint.

There are two of them and neither is silent: the ladder runs out, or it stops early because the response can never succeed — a 404 after your endpoint moved, a 401 after you rotated your own auth, a redirect we do not follow, or a URL that has come to resolve somewhere we refuse to dial. Each ends in the same notice in your dashboard, debounced to one per endpoint per hour. Those are the failures you cannot discover from your side: nothing arrives, and nothing says why.

POST /v1/webhooks/deliveries/{id}/redeliver re-sends the stored payload with a fresh signature and logs a new attempt, reusing the original X-PS-Event-Id. Your endpoint being down for an hour is a recoverable incident, not lost data.

GET /v1/webhooks/deliveries lists every attempt with its status code and outcome, filterable by webhook and by success, keyset-paginated like everything else.

A row in that log is one attempt; its event_id is the logical event it was an attempt at — the same value we sent as X-PS-Event-Id and the same value your dedupe store is keyed on. So the retry ladder’s three rows and every later replay are visibly one event rather than five failures, and ?event_id= answers the question you actually have about an id your handler never saw: did it ever leave, and what did our endpoint say. A delivery log you cannot join to your own records is a list, not a log.

A subscription URL that resolves to a private, loopback, or link-local address is refused rather than delivered to. That is a property of the subscription, so it fails fast instead of burning the retry ladder.

Both 429s — rate_limit_exceeded and daily_quota_exceeded — carry a Retry-After in seconds, computed from the actual window reset. Sleep for it and your next call succeeds. You do not need a guessed backoff schedule on top.

X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (a Unix timestamp in milliseconds) on success and on failure alike — including on an idempotent replay. Daily quota exhaustion adds X-Daily-Limit and X-Daily-Remaining.

Both the per-minute limit (60 req/min) and the daily quota are enforced across your whole account. Creating more keys does not multiply your budget — so a fleet of keys, one per service, has a predictable ceiling rather than an accidental one. See the tiers.

The day's tally is a durable Postgres row incremented in place, so concurrent orders can never each read the same pre-charge total and all slip under the cap. The tally survives a restart or cache flush.

An admitted order that never becomes a standing charge — card declined, fraud gate blocked it, fulfillment rejected and refunded — releases its reservation. A few declines cannot burn a key's entire daily budget and then report it as spent.

If the ledger is unreachable, the check fails open: a cap must never wrongly block a legitimate order. But once a running total is in hand, an over-cap decision is final — a later error cannot wash it out. And a failed release keeps the reservation, which is fail-safe: the cap can only end up more restrictive, never less.