---
title: "Create Stripe Checkout Session"
url: "https://nov18-dev.movespot.fyi/apis/konnect-metering-billing-0/versions/1801ac42-b9c2-4bc2-8094-1177df9ed25c/operations/create-customer-stripe-checkout-session"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/konnect-metering-billing-0/versions/1801ac42-b9c2-4bc2-8094-1177df9ed25c.md

# Create Stripe Checkout Session

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

Operation ID: `create-customer-stripe-checkout-session`

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)

## Request body (required)

Content types: `application/json`

## Responses

- `201` - CreateStripeCheckoutSessionResult created response.
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `410` - Gone

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: Konnect Metering & Billing
  version: 0.0.1
servers:
  - url: https://us.api.konghq.com/v3
    description: United-States Production region
  - url: https://eu.api.konghq.com/v3
    description: Europe Production region
  - url: https://au.api.konghq.com/v3
    description: Australia Production region
  - url: https://me.api.konghq.com/v3
    description: Middle-East Production region
  - url: https://in.api.konghq.com/v3
    description: India Production region
  - url: https://sg.api.konghq.com/v3
    description: Singapore Production region
paths:
  /openmeter/customers/{customerId}/billing/stripe/checkout-sessions:
    post:
      operationId: create-customer-stripe-checkout-session
      summary: Create Stripe Checkout Session
      description: >-
        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.
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ULID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BillingCustomerStripeCreateCheckoutSessionRequest"
      responses:
        "201":
          description: CreateStripeCheckoutSessionResult created response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BillingAppStripeCreateCheckoutSessionResult"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "410":
          $ref: "#/components/responses/Gone"
      tags:
        - OpenMeter Customers
security:
  - systemAccountAccessToken: []
  - personalAccessToken: []
  - konnectAccessToken: []
components:
  schemas:
    ULID:
      description: ULID (Universally Unique Lexicographically Sortable Identifier).
      type: string
      example: 01G65Z755AFWAKHE12NY0CQ9FH
      pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
      title: ULID
    BillingCustomerStripeCreateCheckoutSessionRequest:
      description: >-
        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.
      type: object
      properties:
        stripe_options:
          description: >-
            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).
          type: object
          properties:
            billing_address_collection:
              description: >-
                Whether to collect the customer's billing address.


                Defaults to auto, which only collects the address when necessary
                for tax calculation.
              type: string
              default: auto
              enum:
                - auto
                - required
            cancel_url:
              description: |-
                URL to redirect customers who cancel the checkout session.

                Not allowed when ui_mode is "embedded".
              type: string
            client_reference_id:
              description: >-
                Unique reference string for reconciling sessions with internal
                systems.


                Can be a customer ID, cart ID, or any other identifier.
              type: string
            customer_update:
              description: Controls which customer fields can be updated by the checkout
                session.
              type: object
              properties:
                address:
                  description: |-
                    Whether to save the billing address to customer.address.

                    Defaults to "never".
                  type: string
                  default: never
                  enum:
                    - auto
                    - never
                name:
                  description: |-
                    Whether to save the customer name to customer.name.

                    Defaults to "never".
                  type: string
                  default: never
                  enum:
                    - auto
                    - never
                shipping:
                  description: |-
                    Whether to save shipping information to customer.shipping.

                    Defaults to "never".
                  type: string
                  default: never
                  enum:
                    - auto
                    - never
            consent_collection:
              description: Configuration for collecting customer consent during checkout.
              type: object
              properties:
                payment_method_reuse_agreement:
                  description: Controls the visibility of payment method reuse agreement.
                  type: object
                  properties:
                    position:
                      description: Position and visibility of the payment method reuse agreement.
                      type: string
                      enum:
                        - auto
                        - hidden
                promotions:
                  description: >-
                    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.
                  type: string
                  enum:
                    - auto
                    - none
                terms_of_service:
                  description: >-
                    Requires customers to accept terms of service before
                    payment.


                    Requires a valid terms of service URL in your Stripe
                    Dashboard settings.
                  type: string
                  enum:
                    - none
                    - required
            currency:
              description: >-
                Three-letter ISO 4217 currency code in uppercase.


                Required for payment mode sessions. Optional for setup mode
                sessions.
              type: string
              example: USD
              maxLength: 3
              minLength: 3
              pattern: ^[A-Z]{3}$
            custom_text:
              description: Custom text to display during checkout at various stages.
              type: object
              properties:
                after_submit:
                  description: Text displayed after the payment confirmation button.
                  type: object
                  properties:
                    message:
                      description: The custom message text (max 1200 characters).
                      type: string
                      maxLength: 1200
                shipping_address:
                  description: Text displayed alongside shipping address collection.
                  type: object
                  properties:
                    message:
                      description: The custom message text (max 1200 characters).
                      type: string
                      maxLength: 1200
                submit:
                  description: Text displayed alongside the payment confirmation button.
                  type: object
                  properties:
                    message:
                      description: The custom message text (max 1200 characters).
                      type: string
                      maxLength: 1200
                terms_of_service_acceptance:
                  description: Text replacing the default terms of service agreement text.
                  type: object
                  properties:
                    message:
                      description: The custom message text (max 1200 characters).
                      type: string
                      maxLength: 1200
            expires_at:
              description: >-
                Unix timestamp when the checkout session expires.


                Can be 30 minutes to 24 hours from creation. Defaults to 24
                hours.
              type: integer
              format: int64
            locale:
              description: >-
                IETF language tag for the checkout UI locale.


                If blank or "auto", uses the browser's locale. Example: "en",
                "fr", "de".
              type: string
            metadata:
              description: |-
                Set of key-value pairs to attach to the checkout session.

                Useful for storing additional structured information.
              type: object
              additionalProperties:
                type: string
            return_url:
              description: >-
                Return URL for embedded checkout sessions after payment
                authentication.


                Required if ui_mode is "embedded" and redirect-based payment
                methods are enabled.
              type: string
            success_url:
              description: >-
                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
              type: string
            ui_mode:
              description: >-
                The UI mode for the checkout session.


                "hosted" displays a Stripe-hosted page. "embedded" integrates
                directly into your app.

                Defaults to "hosted".
              type: string
              default: hosted
              enum:
                - embedded
                - hosted
            payment_method_types:
              description: >-
                List of payment method types to enable (e.g., "card",
                "us_bank_account").


                If not specified, Stripe enables all relevant payment methods.
              type: array
              items:
                type: string
            redirect_on_completion:
              description: |-
                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
              type: string
              enum:
                - always
                - if_required
                - never
            tax_id_collection:
              description: Configuration for collecting tax IDs during checkout.
              type: object
              properties:
                enabled:
                  description: |-
                    Enable tax ID collection during checkout.

                    Defaults to false.
                  type: boolean
                  default: false
                required:
                  description: |-
                    Whether tax ID collection is required.

                    Defaults to "never".
                  type: string
                  default: never
                  enum:
                    - if_supported
                    - never
      required:
        - stripe_options
    BillingAppStripeCreateCheckoutSessionResult:
      description: >-
        Result of creating a Stripe Checkout Session.


        Contains all the information needed to redirect customers to the
        checkout

        or initialize an embedded checkout flow.
      type: object
      properties:
        customer_id:
          description: The customer ID in the billing system.
          type: string
          example: 01G65Z755AFWAKHE12NY0CQ9FH
          pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
          title: ULID
        stripe_customer_id:
          description: The Stripe customer ID.
          type: string
        session_id:
          description: The Stripe checkout session ID.
          type: string
        setup_intent_id:
          description: The setup intent ID created for collecting the payment method.
          type: string
        client_secret:
          description: |-
            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
          type: string
        client_reference_id:
          description: |-
            The client reference ID provided in the request.

            Useful for reconciling the session with your internal systems.
          type: string
        customer_email:
          description: Customer's email address if provided to Stripe.
          type: string
        currency:
          description: Currency code for the checkout session.
          type: string
          example: USD
          maxLength: 3
          minLength: 3
          pattern: ^[A-Z]{3}$
        created_at:
          description: Timestamp when the checkout session was created.
          type: string
          format: date-time
          example: 2023-01-01T01:01:01.001Z
          title: RFC3339 Date-Time
        expires_at:
          description: Timestamp when the checkout session will expire.
          type: string
          format: date-time
          example: 2023-01-01T01:01:01.001Z
          title: RFC3339 Date-Time
        metadata:
          description: Metadata attached to the checkout session.
          type: object
          additionalProperties:
            type: string
        status:
          description: |-
            The status of the checkout session.

            See: https://docs.stripe.com/api/checkout/sessions/object#checkout_session_object-status
          type: string
        url:
          description: URL to redirect customers to the checkout page (for hosted mode).
          type: string
        mode:
          description: >-
            Mode of the checkout session.


            Currently only "setup" mode is supported for collecting payment
            methods.
          type: string
          enum:
            - setup
        cancel_url:
          description: The cancel URL where customers are redirected if they cancel.
          type: string
        success_url:
          description: The success URL where customers are redirected after completion.
          type: string
        return_url:
          description: The return URL for embedded sessions after authentication.
          type: string
      required:
        - customer_id
        - stripe_customer_id
        - session_id
        - setup_intent_id
        - created_at
        - mode
    BadRequestError:
      allOf:
        - $ref: "#/components/schemas/BaseError"
        - type: object
          required:
            - invalid_parameters
          properties:
            invalid_parameters:
              $ref: "#/components/schemas/InvalidParameters"
    UnauthorizedError:
      allOf:
        - $ref: "#/components/schemas/BaseError"
        - type: object
          properties:
            status:
              example: 401
            title:
              example: Unauthorized
            type:
              example: https://httpstatuses.com/401
            instance:
              example: kong:trace:1234567890
            detail:
              example: Invalid credentials
    ForbiddenError:
      allOf:
        - $ref: "#/components/schemas/BaseError"
        - type: object
          properties:
            status:
              example: 403
            title:
              example: Forbidden
            type:
              example: https://httpstatuses.com/403
            instance:
              example: kong:trace:1234567890
            detail:
              example: Forbidden
    NotFoundError:
      allOf:
        - $ref: "#/components/schemas/BaseError"
        - type: object
          properties:
            status:
              example: 404
            title:
              example: Not Found
            type:
              example: https://httpstatuses.com/404
            instance:
              example: kong:trace:1234567890
            detail:
              example: Not found
    GoneError:
      allOf:
        - $ref: "#/components/schemas/BaseError"
        - type: object
          properties:
            status:
              example: 410
            title:
              example: Gone
            type:
              example: https://httpstatuses.com/410
            instance:
              example: kong:trace:1234567890
            detail:
              example: Gone
    BaseError:
      description: standard error
      type: object
      properties:
        status:
          description: >
            The HTTP status code of the error. Useful when passing the response

            body to child properties in a frontend UI. Must be returned as an
            integer.
          type: integer
          readOnly: true
        title:
          description: |
            A short, human-readable summary of the problem. It should not
            change between occurences of a problem, except for localization.
            Should be provided as "Sentence case" for direct use in the UI.
          type: string
          readOnly: true
        type:
          description: The error type.
          type: string
          readOnly: true
        instance:
          description: |
            Used to return the correlation ID back to the user, in the format
            kong:trace:<correlation_id>. This helps us find the relevant logs
            when a customer reports an issue.
          type: string
          readOnly: true
        detail:
          description: >
            A human readable explanation specific to this occurence of the
            problem.

            This field may contain request/entity data to help the user
            understand

            what went wrong. Enclose variable values in square brackets. Should
            be

            provided as "Sentence case" for direct use in the UI.
          type: string
          readOnly: true
      required:
        - status
        - title
        - instance
        - detail
      title: Error
    InvalidParameters:
      description: invalid parameters
      type: array
      items:
        oneOf:
          - $ref: "#/components/schemas/InvalidParameterStandard"
          - $ref: "#/components/schemas/InvalidParameterMinimumLength"
          - $ref: "#/components/schemas/InvalidParameterMaximumLength"
          - $ref: "#/components/schemas/InvalidParameterChoiceItem"
          - $ref: "#/components/schemas/InvalidParameterDependentItem"
      minItems: 1
      nullable: false
      uniqueItems: true
    InvalidParameterStandard:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          $ref: "#/components/schemas/InvalidRules"
        source:
          type: string
          example: body
        reason:
          type: string
          example: is a required field
          readOnly: true
      additionalProperties: false
      required:
        - field
        - reason
    InvalidParameterMinimumLength:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          enum:
            - min_length
            - min_digits
            - min_lowercase
            - min_uppercase
            - min_symbols
            - min_items
            - min
          nullable: false
          readOnly: true
        minimum:
          type: integer
          example: 8
        source:
          type: string
          example: body
        reason:
          type: string
          example: must have at least 8 characters
          readOnly: true
      additionalProperties: false
      required:
        - field
        - reason
        - rule
        - minimum
    InvalidParameterMaximumLength:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          enum:
            - max_length
            - max_items
            - max
          nullable: false
          readOnly: true
        maximum:
          type: integer
          example: 8
        source:
          type: string
          example: body
        reason:
          type: string
          example: must not have more than 8 characters
          readOnly: true
      additionalProperties: false
      required:
        - field
        - reason
        - rule
        - maximum
    InvalidParameterChoiceItem:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          enum:
            - enum
          nullable: false
          readOnly: true
        reason:
          type: string
          example: is a required field
          readOnly: true
        choices:
          type: array
          items: {}
          minItems: 1
          nullable: false
          readOnly: true
          uniqueItems: true
        source:
          type: string
          example: body
      additionalProperties: false
      required:
        - field
        - reason
        - rule
        - choices
    InvalidParameterDependentItem:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          enum:
            - dependent_fields
          nullable: true
          readOnly: true
        reason:
          type: string
          example: is a required field
          readOnly: true
        dependents:
          type: array
          items: {}
          nullable: true
          readOnly: true
          uniqueItems: true
        source:
          type: string
          example: body
      additionalProperties: false
      required:
        - field
        - rule
        - reason
        - dependents
    InvalidRules:
      description: invalid parameters rules
      type: string
      enum:
        - required
        - is_array
        - is_base64
        - is_boolean
        - is_date_time
        - is_integer
        - is_null
        - is_number
        - is_object
        - is_string
        - is_uuid
        - is_fqdn
        - is_arn
        - unknown_property
        - missing_reference
        - is_label
        - matches_regex
        - invalid
        - is_supported_network_availability_zone_list
        - is_supported_network_cidr_block
        - is_supported_provider_region
        - type
      nullable: true
      readOnly: true
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/BadRequestError"
    Unauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/UnauthorizedError"
          examples:
            UnauthorizedExample:
              $ref: "#/components/examples/UnauthorizedExample"
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ForbiddenError"
          examples:
            UnauthorizedExample:
              $ref: "#/components/examples/ForbiddenExample"
    NotFound:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/NotFoundError"
          examples:
            NotFoundExample:
              $ref: "#/components/examples/NotFoundExample"
    Gone:
      description: Gone
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/GoneError"
  examples:
    UnauthorizedExample:
      value:
        status: 401
        title: Unauthorized
        instance: kong:trace:8347343766220159418
        detail: Unauthorized
    ForbiddenExample:
      value:
        status: 403
        title: Forbidden
        instance: kong:trace:2723154947768991354
        detail: You do not have permission to perform this action
    NotFoundExample:
      value:
        status: 404
        title: Not Found
        instance: kong:trace:6816496025408232265
        detail: Not Found
  securitySchemes:
    systemAccountAccessToken:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: >
        The system account access token is meant for automations and
        integrations that are not directly associated with a human identity.

        You can generate a system account Access Token by creating a system
        account and then obtaining a system account access token for that
        account.

        The access token must be passed in the header of a request, for example:

        `curl -X GET 'https://global.api.konghq.com/v2/users/' --header
        'Authorization: Bearer spat_i2Ej...'`
    personalAccessToken:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: >
        The personal access token is meant to be used as an alternative to
        basic-auth when accessing Konnect via APIs.

        You can generate a Personal Access Token (PAT) from the [personal access
        token page](https://cloud.konghq.com/global/account/tokens/) in the
        Konnect dashboard.

        The PAT token must be passed in the header of a request, for example:

        `curl -X GET 'https://global.api.konghq.com/v2/users/' --header
        'Authorization: Bearer kpat_xgfT...'`
    konnectAccessToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        The Konnect access token is meant to be used by the Konnect dashboard
        and the decK CLI authenticate with.
```
