---
title: "Create Stripe Checkout Session"
method: POST
path: "/openmeter/customers/{customerId}/billing/stripe/checkout-sessions"
tags: ["OpenMeter Customers"]
---

# Create Stripe Checkout Session

`POST /openmeter/customers/{customerId}/billing/stripe/checkout-sessions`

Create a [Stripe Checkout Session](https://docs.stripe.com/payments/checkout)
for the customer.

Creates a Checkout Session for collecting payment method information from
customers. The session operates in "setup" mode, which collects payment details
without charging the customer immediately. The collected payment method can be
used for future subscription billing.

For hosted checkout sessions, redirect customers to the returned URL. For
embedded sessions, use the client_secret to initialize Stripe.js in your
application.

## Path parameters

- `customerId` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).

## Request body

- BillingCustomerStripeCreateCheckoutSessionRequest — Request to create a Stripe Checkout Session for the customer. Checkout Sessions are used to collect payment method information from customers in a secure, Stripe-hosted interface. This integration uses setup mode to collect payment methods that can be charged later for subscription billing.
  - `stripe_options` BillingAppStripeCreateCheckoutSessionRequestOptions, required — Configuration options for creating a Stripe Checkout Session. Based on Stripe's [Checkout Session API parameters](https://docs.stripe.com/api/checkout/sessions/create).
    - `billing_address_collection` 'auto' | 'required' — Controls whether Checkout collects the customer's billing address.
    - `cancel_url` string — URL to redirect customers who cancel the checkout session. Not allowed when ui_mode is "embedded".
    - `client_reference_id` string — Unique reference string for reconciling sessions with internal systems. Can be a customer ID, cart ID, or any other identifier.
    - `customer_update` BillingAppStripeCreateCheckoutSessionCustomerUpdate — Controls which customer fields can be updated by the checkout session.
      - `address` 'auto' | 'never' — Behavior for updating customer fields from checkout session.
      - `name` 'auto' | 'never' — Behavior for updating customer fields from checkout session.
      - `shipping` 'auto' | 'never' — Behavior for updating customer fields from checkout session.
    - `consent_collection` BillingAppStripeCreateCheckoutSessionConsentCollection — Checkout Session consent collection configuration.
      - `payment_method_reuse_agreement` BillingAppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreement — Payment method reuse agreement configuration.
        - `position` 'auto' | 'hidden' — Position of payment method reuse agreement in the UI.
      - `promotions` 'auto' | 'none' — Promotional communication consent collection setting.
      - `terms_of_service` 'none' | 'required' — Terms of service acceptance requirement.
    - `currency` string — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience.
    - `custom_text` BillingAppStripeCheckoutSessionCustomTextParams — Custom text displayed at various stages of the checkout flow.
      - `after_submit` object — Text displayed after the payment confirmation button.
        - `message` string — The custom message text (max 1200 characters).
      - `shipping_address` object — Text displayed alongside shipping address collection.
        - `message` string — The custom message text (max 1200 characters).
      - `submit` object — Text displayed alongside the payment confirmation button.
        - `message` string — The custom message text (max 1200 characters).
      - `terms_of_service_acceptance` object — Text replacing the default terms of service agreement text.
        - `message` string — The custom message text (max 1200 characters).
    - `expires_at` integer — Unix timestamp when the checkout session expires. Can be 30 minutes to 24 hours from creation. Defaults to 24 hours.
    - `locale` string — IETF language tag for the checkout UI locale. If blank or "auto", uses the browser's locale. Example: "en", "fr", "de".
    - `metadata` object — Set of key-value pairs to attach to the checkout session. Useful for storing additional structured information.
    - `return_url` string — Return URL for embedded checkout sessions after payment authentication. Required if ui_mode is "embedded" and redirect-based payment methods are enabled.
    - `success_url` string — Success URL to redirect customers after completing payment or setup. Not allowed when ui_mode is "embedded". See: https://docs.stripe.com/payments/checkout/custom-success-page
    - `ui_mode` 'embedded' | 'hosted' — Checkout Session UI mode.
    - `payment_method_types` string[] — List of payment method types to enable (e.g., "card", "us_bank_account"). If not specified, Stripe enables all relevant payment methods.
    - `redirect_on_completion` 'always' | 'if_required' | 'never' — Redirect behavior for embedded checkout sessions.
    - `tax_id_collection` BillingAppStripeCreateCheckoutSessionTaxIdCollection — Tax ID collection configuration for checkout sessions.
      - `enabled` boolean — Enable tax ID collection during checkout. Defaults to false.
      - `required` 'if_supported' | 'never' — Tax ID collection requirement level.

## Response `201`

CreateStripeCheckoutSessionResult created response.

- BillingAppStripeCreateCheckoutSessionResult — Result of creating a Stripe Checkout Session. Contains all the information needed to redirect customers to the checkout or initialize an embedded checkout flow.
  - `customer_id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).
  - `stripe_customer_id` string, required — The Stripe customer ID.
  - `session_id` string, required — The Stripe checkout session ID.
  - `setup_intent_id` string, required — The setup intent ID created for collecting the payment method.
  - `client_secret` string — Client secret for initializing Stripe.js on the client side. Required for embedded checkout sessions. See: https://docs.stripe.com/payments/checkout/custom-success-page
  - `client_reference_id` string — The client reference ID provided in the request. Useful for reconciling the session with your internal systems.
  - `customer_email` string — Customer's email address if provided to Stripe.
  - `currency` string — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience.
  - `created_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
  - `expires_at` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
  - `metadata` object — Metadata attached to the checkout session.
  - `status` string — The status of the checkout session. See: https://docs.stripe.com/api/checkout/sessions/object#checkout_session_object-status
  - `url` string — URL to redirect customers to the checkout page (for hosted mode).
  - `mode` 'setup', required — Stripe Checkout Session mode. Determines the primary purpose of the checkout session.
  - `cancel_url` string — The cancel URL where customers are redirected if they cancel.
  - `success_url` string — The success URL where customers are redirected after completion.
  - `return_url` string — The return URL for embedded sessions after authentication.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `410` — Gone

---

[API](https://skmtc.net/openmeterio/apis/openmeter-api.md) · [All operations](https://skmtc.net/openmeterio/apis/openmeter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmeterio/openmeter-api/revisions/327f2080730f/schema)