---
title: "Expire an open checkout session"
method: POST
path: "/api/v1/checkout-sessions/{id}/expire"
tags: ["Checkout"]
---

# Expire an open checkout session

`POST /api/v1/checkout-sessions/{id}/expire`

## Request

- Base URL: `https://merchant.zahlo.eu`
- URL: `https://merchant.zahlo.eu/api/v1/checkout-sessions/{id}/expire`
- Auth: API key in header `x-api-key`

Expire an open checkout session. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.

## Path parameters

- `id` string, required

## Response `200`

Checkout session expired

- CheckoutSession
  - `id` string, required
  - `object` 'checkout_session', required
  - `livemode` boolean
  - `createdAt` string, date-time
  - `type` 'payment' | 'setup' | 'subscription', required
  - `mode` 'hosted' | 'embedded', required
  - `status` 'open' | 'complete' | 'expired' | 'failed', required
  - `paymentStatus` 'unpaid' | 'paid' | 'no_payment_required', required
  - `url` string, uri, nullable: Hosted only, while open: redirect the customer here.
  - `clientToken` string, nullable: Embedded only, while open: pass it to the browser SDK.
  - `detailsRequired` boolean: Embedded only: true until the payer completed Zahlo's details step (the browser SDK mounts it first); embedUrl is null meanwhile.
  - `embedUrl` string, uri, nullable
  - `expiresAt` string, date-time, required
  - `currency` string, required
  - `amountSubtotal` integer
  - `amountDiscount` integer
  - `amountShipping` integer: The chosen shipping option, inside amountTotal; 0 without one.
  - `amountTotal` integer, required
  - `shippingOptions` object[]: The offered shipping rates with their amount at session create, in order.
    - `shippingRate` string, required
    - `shippingAmount` integer, required
  - `shippingCost` object, nullable: The chosen shipping option. amountTax is 0: VAT is inside the amount. Discounts never apply to shipping.
    - `amountSubtotal` integer, required
    - `amountTax` integer, required
    - `amountTotal` integer, required
    - `shippingRate` string, required
  - `lineItems` object[], required
    - `name` string
    - `quantity` integer
    - `unitAmountMinor` integer
    - `amountMinor` integer
    - `priceId` string, nullable
    - `adjustableQuantity` object: Present when the payer may change this line's quantity.
      - `enabled` boolean
      - `minimum` integer
      - `maximum` integer
  - `customerId` string, nullable
  - `setupFutureUsage` 'off_session', nullable: Set when the session saves the card for off-session charges.
  - `customerEmail` string, nullable
  - `couponId` string, nullable
  - `paymentId` string, nullable
  - `subscriptionId` string, nullable
  - `reference` string, nullable
  - `customFields` CustomField[]: The session's custom fields with the payer's answers; empty when it asks none.
    - `key` string, required
    - `label` object, required
      - `type` 'custom', required
      - `custom` string, required
    - `type` 'dropdown' | 'text', required
    - `optional` boolean, required
    - `dropdown` object, nullable, required
      - `options` object[], required
        - `label` string, required
        - `value` string, required
      - `defaultValue` string, nullable, required
      - `value` string, nullable, required
    - `text` object, nullable, required
      - `minimumLength` integer, nullable, required
      - `maximumLength` integer, nullable, required
      - `defaultValue` string, nullable, required
      - `value` string, nullable, required
  - `phoneNumberCollection` object: The details page asks for a phone number.
    - `enabled` boolean, required
  - `nameCollection` object: The details page asks for a full name and/or a business name.
    - `individual` object, required
      - `enabled` boolean, required
    - `business` object, required
      - `enabled` boolean, required
  - `consentCollection` object
    - `promotions` 'auto' | 'none', required
    - `termsOfService` 'required' | 'none', required
  - `allowPromotionCodes` boolean
  - `submitType` 'auto' | 'pay' | 'book' | 'donate'
  - `brandingSettings` object, nullable: This session's branding override; null fields fall back to Account → Branding.
    - `brandColor` string, nullable
    - `logoUrl` string, nullable
    - `displayName` string, nullable
  - `taxIdCollection` object
    - `enabled` boolean, required
  - `customerDetails` object: What the payer entered on the details page; null until then.
    - `email` string, nullable, required
    - `phone` string, nullable, required
    - `individualName` string, nullable, required
    - `businessName` string, nullable, required
  - `consent` object
    - `promotions` 'opt_in' | 'opt_out', nullable, required
    - `termsOfService` 'accepted', nullable, required
  - `shippingDetails` object, nullable: The shipping address the payer entered on Zahlo's page, for a payment link or a session with `shippingAddressCollection`.
    - `name` string, required
    - `address` object, required
      - `line1` string, required
      - `line2` string, nullable, required
      - `city` string, required
      - `postalCode` string, required
      - `country` string, required: ISO 3166-1 alpha-2
  - `successUrl` string
  - `cancelUrl` string
  - `locale` string
  - `paymentMethodTypes` string[]
  - `appearance` CheckoutAppearance
    - `theme` 'light' | 'dark' | 'auto'
    - `logoUrl` string, uri
    - `iconUrl` string, uri
    - `fontFamily` string
    - `colors` object
    - `spacing` 'compact' | 'normal' | 'comfortable'
    - `customCss` string
  - `metadata` object: Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `404`: Resource not found
- `409`: Request conflicts with existing state

---

[API](https://skmtc.dev/zahlo/apis/zahlo-merchant-api.md) - [All operations](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/revisions/8fcbef981e0d?raw)