Idempotency, pages and metadata
Shared request rules for predictable retries and exact data.
On this page
Idempotency
Idempotency prevents duplicate operations when the same request is retried. Creates require an Idempotency-Key header between 1 and 255 UTF-8 bytes.
The same profile, key and normalized request return the existing object with HTTP 200. A changed body returns 409 idempotency_conflict. New objects return 201.
Save one key for each purchase attempt. A random key created anew on every retry defeats duplicate protection.
Pagination
Invoice, checkout-session and webhook-event lists return {items, nextCursor}, newest first. limit accepts 1–100 and defaults to 50.
Pass nextCursor as cursor for the next request. A null nextCursor means there are no more pages. Keep any filters the same while paging.
The store and token endpoints return their complete scoped lists instead of cursor pages.
{
"items": [],
"nextCursor": null
}Metadata
Attach your own order identifier with metadata at create time. You can set up to 20 keys, each 1–40 letters, digits, underscores or hyphens.
Values are single-line plain text up to 500 characters. Metadata is immutable, appears in owner reads and webhooks, and defaults to {}.
Public pay pages and PDFs do not show metadata. Keep credentials, personal secrets and payment authorization out of it.
Money representation
amountUsd is an exact decimal string such as 1250.00. amount is an integer string in token base units. Never use floating-point math for money.
A token with six decimals represents 1250 tokens as 1250000000 base units. Use bigint for arithmetic and preserve strings across JSON.
Identify a token by chainId and contract address together. A ticker or icon does not identify an enabled payment asset.