Store a Stripe Checkout Session

Use this browser endpoint immediately after your server creates Stripe Checkout and before redirecting or mounting Checkout. It stores attribution only. It does not create a sale and does not prove payment.

POST https://biq.li/api/v1/integrations/stripe/checkout-sessions

The @biqli/analytics method storeStripeSession() is the recommended client. It reads the SDK’s current click ID, adds a fresh idempotency key, and sends the authenticated request.

SDK request

const result = await biqli.storeStripeSession({
  stripe_account_id: 'acct_example123',
  stripe_environment: 'live',
  stripe_session_id: 'cs_live_example123',
  customer_email: 'buyer@example.com',
});

window.location.assign(checkoutUrl);

If you loaded the global browser script:

const result = await window.Biqli.storeStripeSession({
  stripe_account_id: 'acct_example123',
  stripe_environment: 'sandbox',
  stripe_session_id: 'cs_test_example123',
});

The SDK uses the stored bq_id. You can pass bq_id explicitly only when your application already obtained and validated the click ID through the same browser attribution flow.

Authentication and origin

Send the workspace publishable key as a bearer token:

Authorization: Bearer biqli_pk_xxxxxxxxx

The request must come from a valid browser Origin whose hostname is allowed in the workspace tracking settings. The publishable key, allowed hostname, click, and Stripe connection must all belong to the same workspace. Do not use a secret workspace API key for this browser endpoint. Never expose a Stripe secret or restricted key in the request.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer` plus an active `biqli_pk_...` publishable key.
`Origin`	Yes	Browser-supplied origin. Its hostname must be allowed for the workspace.
`Content-Type`	Yes	Must be `application/json`.
`Accept`	Recommended	Use `application/json`.
`Idempotency-Key`	Yes	From 1 to 255 printable characters. The browser SDK generates one for every call.
`X-Biq-Client`	Recommended	Client name for diagnostics.
`X-Biq-Client-Version`	Recommended	Client version for diagnostics.
`X-Biq-Request-Id`	Recommended	Caller-generated safe request identifier. Biqli also returns its request ID.

The JSON request body cannot exceed 8,192 bytes.

Request fields

The endpoint rejects unknown fields.

Field	Type	Required	Description
`stripe_account_id`	`string`	Yes	Connected Stripe account ID matching `acct_...`.
`stripe_environment`	`'live' \| 'test' \| 'sandbox'`	Conditional	Selects the connection environment. Required when the same account reference has more than one eligible active mode. Supplying it is recommended.
`stripe_session_id`	`string`	Recommended	Exact `cs_live_...` or `cs_test_...` Checkout Session ID created by your server. Its mode must match the connection.
`customer_email`	`string`	No	RFC-valid email up to 254 characters. Used only for safe identity enrichment or the bounded unique-email fallback.
`bq_id`	`string`	Yes at the API	Valid Biqli click ID, up to 100 URL-safe identifier characters. The SDK supplies its current stored click when omitted from the method input.

Exact mapping request

curl --request POST \
  --url https://biq.li/api/v1/integrations/stripe/checkout-sessions \
  --header "Authorization: Bearer $BIQLI_PUBLISHABLE_KEY" \
  --header 'Origin: https://app.example.com' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: stripe-checkout-attempt-1842' \
  --data '{
    "stripe_account_id": "acct_example123",
    "stripe_environment": "live",
    "stripe_session_id": "cs_live_example123",
    "customer_email": "buyer@example.com",
    "bq_id": "fGQimsCLcpoa"
  }'

Use the raw request only for debugging a browser-equivalent request. A server without a browser Origin is rejected by design.

Pending fallback request

You can omit stripe_session_id when it is not yet available:

{
  "stripe_account_id": "acct_example123",
  "stripe_environment": "sandbox",
  "customer_email": "buyer@example.com",
  "bq_id": "fGQimsCLcpoa"
}

This creates a short-lived pending candidate. Biqli later accepts it only when the customer email matches exactly one eligible, unconsumed candidate. Multiple candidates are ambiguous and fail closed. Prefer the exact mapping request.

Response

A new registration returns 201 Created:

{
  "checkout": {
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "status": "pending",
    "expiresAt": "2026-12-26T10:30:00+00:00"
  },
  "request_id": "7ed1e7ea-8e49-4d4f-9eb8-f3221fc54251"
}

An existing compatible registration can return 200 OK. checkout.id is Biqli’s public registration ID, not the Stripe Checkout Session ID.

Response field	Meaning
`checkout.id`	Public Biqli checkout-attribution registration ID.
`checkout.status`	Mapping state: `pending`, `consumed`, `awaiting_payment`, `paid`, or `payment_failed`. A normal pre-Checkout registration starts as `pending`.
`checkout.expiresAt`	UTC expiration of this attribution registration.
`request_id`	Biqli request identifier for diagnostics. Also returned in `X-Biq-Request-Id`.

Exact Checkout mappings default to a 90-day eligibility window. Pending registrations without a Session ID default to 24 hours. Treat these as upper bounds, not a reason to delay payment.

Idempotency

The endpoint requires Idempotency-Key.

Repeating the same key and canonical request returns the original response and adds Idempotency-Replayed: true.
Reusing the key with different request data returns 409 idempotency_conflict.
Attempting to bind an existing Stripe Checkout identity to another click returns 409 stripe_attribution_conflict.
Idempotency records are retained for seven days.

The browser SDK creates a new idempotency key per method call. If your UI retries after an unknown network outcome and you need response replay, call the API with a stable attempt key or retain the first successful response in your application state.

Errors

Errors use Biqli’s structured API error format unless a readiness failure occurs before the controller.

Status	Code	Meaning
`401`	`invalid_token`	Publishable key is missing, invalid, or revoked.
`403`	`origin_required`	No valid browser `Origin` was supplied.
`403`	`hostname_not_configured`	The workspace has no allowed hostname.
`403`	`origin_not_allowed`	The request hostname is not allowed for this workspace.
`403`	`tracking_disabled`	Client conversion tracking is disabled or unavailable.
`405`	`method_not_allowed`	The endpoint only accepts `POST`.
`409`	`idempotency_conflict`	The idempotency key was reused with different data.
`409`	`stripe_account_not_connected`	No active connection matches the workspace and Stripe account.
`409`	`stripe_environment_required`	More than one active mode is eligible; specify the environment.
`409`	`stripe_attribution_conflict`	The Stripe Checkout identity is already linked to another click.
`422`	`idempotency_key_required`	No `Idempotency-Key` header was supplied.
`422`	`invalid_click_id`	The click is invalid, expired, inactive, or belongs to another workspace.
`422`	`stripe_mode_mismatch`	The `cs_live_...` or `cs_test_...` ID conflicts with the connection mode.
`422`	`validation_error`	JSON, body size, field names, types, formats, or idempotency-key syntax are invalid.
`429`	`rate_limit_exceeded`	This publishable key and IP exceeded the client tracking limit. Respect `Retry-After`.
`503`	—	Stripe App connection handling is temporarily unavailable.

The client tracking limit is 120 requests per 60 seconds for a publishable-key and IP pair. Responses include standard and X-RateLimit-* diagnostic headers.

SDK errors

The browser method throws BiqliError. Two client-side errors can occur before an HTTP request:

consent_required when browser tracking consent is disabled;
missing_click_id when neither an explicit nor stored valid click ID exists.

Handle them before opening Checkout:

try {
  await biqli.storeStripeSession(input);
  window.location.assign(checkoutUrl);
} catch (error) {
  // Keep the customer on your page and offer a safe retry.
  showCheckoutAttributionError(error);
}

Read Implement Stripe Checkout for the complete server and browser sequence.

GETTING STARTED

SDKs

BIQLI LINKS API

Store a Stripe Checkout Session

SDK request

Authentication and origin

Headers

Request fields

Exact mapping request

Pending fallback request

Response

Idempotency

Errors

SDK errors

​SDK request

​Authentication and origin

​Headers

​Request fields

​Exact mapping request

​Pending fallback request

​Response

​Idempotency

​Errors

​SDK errors

SDK request

Authentication and origin

Headers

Request fields

Exact mapping request

Pending fallback request

Response

Idempotency

Errors

SDK errors