---
title: "Search checkout sessions"
method: POST
path: "/checkout/sessions/search"
tags: ["Checkout"]
---

# Search checkout sessions

`POST /checkout/sessions/search`

Use when listing or searching checkout sessions. Returns a paginated list; supports filtering by customer IDs, statuses, and other fields.

## Request body

- TypesCheckoutSessionFilter
  - `actions` TypesCheckoutAction[]
  - `checkout_invoice_ids` string[]
  - `checkout_payment_ids` string[]
  - `checkout_statuses` TypesCheckoutStatus[]
  - `customer_ids` string[]
  - `expand` string
  - `expires_at_lt` string
  - `limit` integer
  - `offset` integer
  - `order` 'asc' | 'desc'
  - `payment_providers` TypesCheckoutPaymentProvider[]
  - `sort` string
  - `status` 'published' | 'deleted' | 'archived'

## Response `200`

OK

- ListCheckoutSessionsResponse
  - `items` CheckoutSessionResponse[]
    - `action` 'create_subscription'
    - `cancel_url` string
    - `cancelled_at` string, date-time
    - `checkout_invoice_id` string — CheckoutInvoiceID and CheckoutPaymentID are set once the apply step creates the corresponding Flexprice entities (completed sessions only).
    - `checkout_payment_id` string
    - `checkout_status` 'initiated' | 'pending' | 'completed' | 'failed' | 'expired'
    - `completed_at` string, date-time
    - `configuration` TypesCheckoutConfiguration
      - `create_subscription_params` TypesCreateSubscriptionParams
        - `billing_cycle` 'anniversary' | 'calendar'
        - `billing_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' | 'ONETIME', required
        - `billing_period_count` integer
        - `credit_grants` TypesCheckoutCreditGrant[]
          - `amount` string
          - `currency` string
          - `expires_at` string, date-time
          - `metadata` object
          - `name` string
        - `currency` string, required
        - `end_date` string, date-time
        - `line_items` TypesCheckoutLineItem[]
          - `price_id` string
          - `quantity` integer
        - `lookup_key` string
        - `metadata` object
        - `plan_id` string, required
        - `start_date` string, date-time
        - `subscription_coupons` TypesCheckoutCouponInput[]
          - `coupon_code` string
          - `price_id` string
    - `created_at` string, date-time
    - `created_by` string
    - `customer_id` string
    - `environment_id` string
    - `expires_at` string, date-time — ExpiresAt is required. A Temporal timer fires at this time for any session still in initiated|pending, marking it expired. The caller must create a new session after expiry (expire-and-restart model).
    - `failure_reason` string — FailureReason is a human-readable string set on failed sessions.
    - `failure_url` string
    - `id` string
    - `idempotency_key` string — IdempotencyKey is caller-supplied. It is unique only while the session is active (initiated|pending). The same key may be reused once the session reaches a terminal state (completed|failed|expired).
    - `metadata` object
    - `payment_action` PaymentAction
      - `type` 'checkout_url' | 'payment_link'
      - `url` string
    - `payment_provider` 'stripe'
    - `provider_result` TypesCheckoutProviderResult
      - `create_subscription_result` TypesProviderSubscriptionResult
        - `payment_intent_id` string
        - `session_id` string
        - `session_url` string
    - `result` TypesCheckoutResult
      - `create_subscription_result` TypesCreateSubscriptionResult
        - `invoice_id` string
        - `payment_id` string
        - `subscription_id` string
    - `status` 'published' | 'deleted' | 'archived'
    - `success_url` string — Redirect URLs sent to the payment provider. The provider redirects the user browser to the appropriate URL after the payment flow completes.
    - `tenant_id` string
    - `updated_at` string, date-time
    - `updated_by` string
  - `pagination` TypesPaginationResponse
    - `limit` integer
    - `offset` integer
    - `total` integer

## Other responses

- `400` — Invalid filter
- `500` — Server error

## Changes

- **2026-06-24** `08e2dac200bb` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/flexprice/apis/flexprice-api/changes/checkout/sessions/search/post.md)

---

[API](https://skmtc.dev/flexprice/apis/flexprice-api.md) · [All operations](https://skmtc.dev/flexprice/apis/flexprice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexprice/apis/flexprice-api/revisions/08e2dac200bb?raw)