# Expire a checkout session

> The checkout.sessions.expire operation: POST /api/v1/checkout/sessions/{id}/expire in the REST API and the checkout_sessions_expire tool in the MCP server.

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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).