Create checkout session
POST/api/v1/checkout/sessions
Requires a caller-generated nonblank Idempotency-Key of at most 64 characters. Persist the key and original request before dispatch. The authenticated organization, location and key identify a durable create; the original request fingerprint is frozen. Repeating the same request replays that session before mutable capability, payment-policy or tax validation. Reusing the identity with changed input returns HTTP 409. A replay does not reprice or reopen an expired, cancelled or completed session. For a new identity, AUTOMATIC tax is quoted before persistence and requoted when pricing or destination changes. Tax-provider outages fail closed with HTTP 503 UPSTREAM_UNAVAILABLE. PRECOMPUTED freezes caller-supplied line tax. At cutover, retained legacy successes are verified using their old sanitized request hash and canonical persisted owner, then adopt the original session ID and freeze the current full typed body for later retries. This does not prove fields excluded from the old hash, such as expiresIn or scrubbed metadata. Legacy in-progress entries fail closed. Already-purged legacy keys cannot be recovered; operators must census and fence in-flight legacy attempts during rollout. The permanent guarantee covers retained/adopted and newly durable identities, not purged history.
Request
Responses
- 200
- 400
- 401
- 409
- 503
Checkout session created.
Invalid request payload or query parameters.
Missing or invalid bearer token.
The durable identity was already used with a different request fingerprint.
Tax-provider outage returns UPSTREAM_UNAVAILABLE; no checkout session is created. Recover the original identity with the authenticated by-key lookup before retrying; an unavailable lookup is not proof of absence.