checkout reference

This reference follows the current server implementation. Use the SDK for customer flows; it manages identity proof and retries. Authentication and errors apply to every endpoint. Types below describe JSON: dates are ISO strings, ? means optional, and null differs from an omitted field. Responses may include additional fields. Schemas also enforce constraints that TypeScript cannot express; download the request JSON Schemas. Named response types are defined in the data model reference.

POST /v1/checkout/stripe/start

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ productPriceId: string;
  returnUrl: string;
  placementId?: string | undefined;
  campaignId?: string | undefined;
  campaignAudienceId?: string | undefined;
  campaignVariantId?: string | undefined;
  campaignAssignmentId?: string | undefined;
  paywallId?: string | undefined;
  paywallProductId?: string | undefined;
  }

Response

JSON response shape

{ url: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: startStripeCheckout.

GET /v1/checkout/stripe/continue

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Use the path parameters above and any query options described below.

Handler inputs: state. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ url: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: continueStripeCheckout.

POST /v1/checkout/stripe/verify

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ sessionId: string }

Response

JSON response shape

{ purchaseVerified: boolean;
  success: true;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: verifyStripeSession.

POST /v1/checkout/stripe/portal

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ returnUrl: string }

Response

JSON response shape

{ url: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: createStripePortalSession.