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

# Create Stripe Checkout Session

`POST /v3/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` object, required — Options for configuring the Stripe Checkout Session. These options are passed directly to Stripe's [checkout session creation API](https://docs.stripe.com/api/checkout/sessions/create).
    - `billing_address_collection` 'auto' | 'required' — Whether to collect the customer's billing address. Defaults to auto, which only collects the address when necessary for tax calculation.
    - `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` object — Controls which customer fields can be updated by the checkout session.
      - `address` 'auto' | 'never' — Whether to save the billing address to customer.address. Defaults to "never".
      - `name` 'auto' | 'never' — Whether to save the customer name to customer.name. Defaults to "never".
      - `shipping` 'auto' | 'never' — Whether to save shipping information to customer.shipping. Defaults to "never".
    - `consent_collection` object — Configuration for collecting customer consent during checkout.
      - `payment_method_reuse_agreement` object — Controls the visibility of payment method reuse agreement.
        - `position` 'auto' | 'hidden' — Position and visibility of the payment method reuse agreement.
      - `promotions` 'auto' | 'none' — Enables collection of promotional communication consent. Only available to US merchants. When set to "auto", Checkout determines whether to show the option based on the customer's locale.
      - `terms_of_service` 'none' | 'required' — Requires customers to accept terms of service before payment. Requires a valid terms of service URL in your Stripe Dashboard settings.
    - `currency` string — Three-letter ISO 4217 currency code in uppercase. Required for payment mode sessions. Optional for setup mode sessions.
    - `custom_text` object — Custom text to display during checkout at various stages.
      - `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' — The UI mode for the checkout session. "hosted" displays a Stripe-hosted page. "embedded" integrates directly into your app. Defaults to "hosted".
    - `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. Controls when to redirect users after completion. See: https://docs.stripe.com/payments/checkout/custom-success-page?payment-ui=embedded-form
    - `tax_id_collection` object — Configuration for collecting tax IDs during checkout.
      - `enabled` boolean — Enable tax ID collection during checkout. Defaults to false.
      - `required` 'if_supported' | 'never' — Whether tax ID collection is required. Defaults to "never".

## 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 — The customer ID in the billing system.
  - `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 — Currency code for the checkout session.
  - `created_at` string, date-time, required — Timestamp when the checkout session was created.
  - `expires_at` string, date-time — Timestamp when the checkout session will expire.
  - `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 — Mode of the checkout session. Currently only "setup" mode is supported for collecting payment methods.
  - `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/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.net/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kong/konnect-api-go-sdk/revisions/b576ea92fca2/schema)