Expire a checkout session · Ownrecord docs

Ends an open or blocked checkout session now, so its link stops working (for example when the cart changed). Emits checkout.session.expired. Expiring an expired session changes nothing. A session that is paid, or whose payment is being processed, can't be expired (checkout_session_not_open).

At a glance

REST: POST /api/v1/checkout/sessions/{id}/expire
MCP tool: checkout_sessions_expire
Operation ID: checkout.sessions.expire
Scope: Brand
Permission: checkout:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the checkout:write scope
Since: M4

Request

Path parameters

Field	Type	Description
`id`	`cs_…` ID	The checkout session's ID (`cs_…`).

Body

This operation takes no body.

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`cs_…` ID
`object`	`"checkout.session"`
`livemode`	boolean
`entityId`	`ent_…` ID
`brandId`	`brd_…` ID
`mode`	one of `payment`, `subscription`, `topup`, `setup`
`status`	one of `open`, `processing`, `complete`, `expired`, `blocked`	`open`, `blocked` (the sale is paused for the customer's location), `processing`, `complete` or `expired`.
`url`	string or null	The hosted page (with its session key); null once complete or expired.
`lineItems`	array of object
`lineItems[].id`	string	The line's ID in the session's quotes and its invoice.
`lineItems[].priceId`	`price_…` ID
`lineItems[].productId`	`prod_…` ID
`lineItems[].priceType`	one of `one_time`, `credit_pack`, `recurring`
`lineItems[].recurring`	object or null	Recurring prices (subscription sessions): the billing interval and whether usage is metered.
`lineItems[].adjustableQuantity`	object or null	The customer may change the quantity on the hosted page within these bounds.
`lineItems[].discount`	money or null	Subscription sessions: what the promotion code takes off this line on the first invoice.
`lineItems[].description`	string	The product's name when the session was created.
`lineItems[].quantity`	integer
`lineItems[].customAmount`	money or null
`lineItems[].amount`	money	Before tax and discounts: gross for tax-inclusive prices, net for exclusive ones (a recurring price's first full period; zero for metered usage, billed later).
`lineItems[].taxBehavior`	one of `inclusive`, `exclusive`
`currency`	string
`customerId`	`cus_…` ID or null
`customerEmail`	string or null
`successUrl`	string or null
`cancelUrl`	string or null
`locale`	string or null
`collectBusinessDetails`	one of `auto`, `required`, `never`
`allowPromotionCodes`	boolean	The hosted page offers a promotion code field.
`promotionCodeId`	`promo_…` ID or null	The promotion code applied to the session.
`subscriptionData`	object or null	Subscription sessions: the trial and the subscription's metadata.
`taxQuoteId`	`tq_…` ID or null	The current quote (`tax.quotes.get` explains it).
`totals`	object or null	The current quote's totals; null before the customer's details.
`blockedReason`	one of `evidence_conflict`, `unsupported_tax_category`, `registration_required`, `rate_unavailable`, `jurisdiction_blocked`, `tax_id_unavailable` or null
`waitlistEntryId`	`wl_…` ID or null
`paymentId`	`pay_…` ID or null
`invoiceId`	`inv_…` ID or null
`subscriptionId`	`sub_…` ID or null	Subscription sessions: the subscription created; setup sessions: the one the method is for.
`paymentMethodId`	`pm_…` ID or null	The payment method saved (subscription and setup sessions).
`expiresAt`	date-time
`completedAt`	date-time or null
`createdAt`	date-time
`metadata`	object

Examples

Expire an open session

HTTP

POST /api/v1/checkout/sessions/cs_01m4tx5nj8emwbyf7y9vcf48aa/expire
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14

Response (200):

JSON

{
  "id": "cs_01m4tx5nj8emwbyf7y9vcf48aa",
  "object": "checkout.session",
  "livemode": false,
  "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "mode": "payment",
  "status": "expired",
  "url": null,
  "lineItems": [
    {
      "id": "1",
      "priceId": "price_01m4tx5nj8emwbyf7y9vcf48ad",
      "productId": "prod_01m4tx5nj8emwbyf7y9vcf48ae",
      "priceType": "credit_pack",
      "recurring": null,
      "adjustableQuantity": null,
      "discount": null,
      "description": "Genno credits",
      "quantity": 1,
      "customAmount": null,
      "amount": {
        "amount": "100000000",
        "currency": "EUR"
      },
      "taxBehavior": "inclusive"
    }
  ],
  "currency": "EUR",
  "customerId": null,
  "customerEmail": "anna@example.com",
  "successUrl": "https://shop.example/thanks",
  "cancelUrl": "https://shop.example/cart",
  "locale": null,
  "collectBusinessDetails": "auto",
  "allowPromotionCodes": false,
  "promotionCodeId": null,
  "subscriptionData": null,
  "taxQuoteId": null,
  "totals": null,
  "blockedReason": null,
  "waitlistEntryId": null,
  "paymentId": null,
  "invoiceId": null,
  "subscriptionId": null,
  "paymentMethodId": null,
  "expiresAt": "2026-10-15T10:00:00.000Z",
  "completedAt": null,
  "createdAt": "2026-10-14T10:00:00.000Z",
  "metadata": {
    "order": "ord_1042"
  }
}

Errors

Code	HTTP status	When	What to do
`resource_not_found`	404	No such checkout session for this brand and mode, or (on the hosted page) the session key is missing or wrong.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`checkout_session_not_open`	409	The session is complete, expired, or a payment for it is being processed (`details.status`).	The session is complete, expired or waiting for a payment's outcome (`details.status`). Create a new session for a new purchase.

It can also return these common errors: validation_failed, api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, permission_denied, scope_required, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Expire an open session#

Errors#