--- title: "Create checkout session" method: POST path: "/api/v1/stripe/checkout/sessions" tags: ["App: Stripe"] --- # Create checkout session `POST /api/v1/stripe/checkout/sessions` Create checkout session. ## Request body - CreateStripeCheckoutSessionRequest — Create Stripe checkout session request. - `appId` string — If not provided, the default Stripe app is used if any. - `customer` union, required — Provide a customer ID or key to use an existing OpenMeter customer. or provide a customer object to create a new customer. - CustomerId — Create Stripe checkout session with customer ID. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - CustomerKey — Create Stripe checkout session with customer key. - `key` string, required - CustomerCreate — Resource create operation model. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `key` string — An optional unique key of the customer. Either key or usageAttribution.subjectKeys must be provided. Useful to reference the customer in external systems. For example, your database ID. - `usageAttribution` CustomerUsageAttribution — Mapping to attribute metered usage to the customer. One customer can have zero or more subjects, but one subject can only belong to one customer. - `subjectKeys` string[], required — The subjects that are attributed to the customer. Can be empty when no subjects are associated with the customer. - `primaryEmail` string — The primary email address of the customer. - `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. - `billingAddress` Address — Address - `country` string — [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 country code. Custom two-letter country codes are also supported for convenience. - `postalCode` string — Postal code. - `state` string — State or province. - `city` string — City. - `line1` string — First line of the address. - `line2` string — Second line of the address. - `phoneNumber` string — Phone number. - `stripeCustomerId` string — Stripe customer ID. If not provided OpenMeter creates a new Stripe customer or uses the OpenMeter customer's default Stripe customer ID. - `options` CreateStripeCheckoutSessionRequestOptions, required — Create Stripe checkout session options See https://docs.stripe.com/api/checkout/sessions/create - `billingAddressCollection` 'auto' | 'required' — Specify whether Checkout should collect the customer’s billing address. - `cancelURL` string — If set, Checkout displays a back button and customers will be directed to this URL if they decide to cancel payment and return to your website. This parameter is not allowed if ui_mode is embedded. - `clientReferenceID` string — A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems. - `customerUpdate` CreateStripeCheckoutSessionCustomerUpdate — Controls what fields on Customer can be updated by the Checkout Session. - `address` 'auto' | 'never' — Create Stripe checkout session customer update behavior. - `name` 'auto' | 'never' — Create Stripe checkout session customer update behavior. - `shipping` 'auto' | 'never' — Create Stripe checkout session customer update behavior. - `consentCollection` CreateStripeCheckoutSessionConsentCollection — Configure fields for the Checkout Session to gather active consent from customers. - `paymentMethodReuseAgreement` CreateStripeCheckoutSessionConsentCollectionPaymentMethodReuseAgreement — Create Stripe checkout session payment method reuse agreement. - `position` 'auto' | 'hidden' — Create Stripe checkout session consent collection agreement position. - `promotions` 'auto' | 'none' — Create Stripe checkout session consent collection promotions. - `termsOfService` 'none' | 'required' — Create Stripe checkout session consent collection terms of service. - `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. - `customText` CheckoutSessionCustomTextAfterSubmitParams — Stripe CheckoutSession.custom_text - `afterSubmit` object — Custom text that should be displayed after the payment confirmation button. - `message` string - `shippingAddress` object — Custom text that should be displayed alongside shipping address collection. - `message` string - `submit` object — Custom text that should be displayed alongside the payment confirmation button. - `message` string - `termsOfServiceAcceptance` object — Custom text that should be displayed in place of the default terms of service agreement text. - `message` string - `expiresAt` integer — The Epoch time in seconds at which the Checkout Session will expire. It can be anywhere from 30 minutes to 24 hours after Checkout Session creation. By default, this value is 24 hours from creation. - `locale` string - `metadata` object — Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata. - `returnURL` string — The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method’s app or site. This parameter is required if ui_mode is embedded and redirect-based payment methods are enabled on the session. - `successURL` string — The URL to which Stripe should send customers when payment or setup is complete. This parameter is not allowed if ui_mode is embedded. If you’d like to use information from the successful Checkout Session on your page, read the guide on customizing your success page: https://docs.stripe.com/payments/checkout/custom-success-page - `uiMode` 'embedded' | 'hosted' — Stripe CheckoutSession.ui_mode - `paymentMethodTypes` string[] — A list of the types of payment methods (e.g., card) this Checkout Session can accept. - `redirectOnCompletion` 'always' | 'if_required' | 'never' — Create Stripe checkout session redirect on completion. - `taxIdCollection` CreateCheckoutSessionTaxIdCollection — Create Stripe checkout session tax ID collection. - `enabled` boolean, required — Enable tax ID collection during checkout. Defaults to false. - `required` 'if_supported' | 'never' — Create Stripe checkout session tax ID collection required. ## Response `201` The request has succeeded and a new resource has been created as a result. - CreateStripeCheckoutSessionResult — Create Stripe Checkout Session response. - `customerId` string, required — The OpenMeter customer ID. - `stripeCustomerId` string, required — The Stripe customer ID. - `sessionId` string, required — The checkout session ID. - `setupIntentId` string, required — The checkout session setup intent ID. - `clientSecret` string — The client secret of the checkout session. This can be used to initialize Stripe.js for your client-side implementation. - `clientReferenceId` string — A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems. - `customerEmail` string — Customer's email address 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. - `createdAt` string, date-time, required — Timestamp at which the checkout session was created. - `expiresAt` string, date-time — Timestamp at which the checkout session will expire. - `metadata` object — Set of key-value pairs attached to the checkout session. - `status` string — The status of the checkout session. - `url` string — URL to show the checkout session. - `mode` 'setup', required — Stripe CheckoutSession.mode - `cancelURL` string — Cancel URL. - `successURL` string — Success URL. - `returnURL` string — Return URL. ## Other responses - `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). - `401` — The request has not been applied because it lacks valid authentication credentials for the target resource. - `403` — The server understood the request but refuses to authorize it. - `404` — The origin server did not find a current representation for the target resource or is not willing to disclose that one exists. - `412` — One or more conditions given in the request header fields evaluated to false when tested on the server. - `500` — The server encountered an unexpected condition that prevented it from fulfilling the request. - `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. - `default` — An unexpected error response. --- [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/1cd97f063f4a/schema)