> ## Documentation Index > Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Checkout Session > Create Checkout Session ## OpenAPI ````yaml openapi/v1-en.yaml POST /api/v1/session openapi: 3.0.3 info: title: Subotiz API description: Subotiz OpenAPI version: 1.0.0 servers: - url: https://{api}.subotiz.com variables: api: default: api security: - sec0: [] tags: - name: Subscription description: Subscription - name: Price description: Price - name: Trade description: Trade - name: Payment description: Payment - name: Checkout Session description: Checkout Session - name: Customer description: Customer - name: Customer Portal description: Customer Portal paths: /api/v1/session: post: tags: - Checkout Session summary: Create Checkout Session description: Create Checkout Session operationId: v1-checkout-session-create-checkout-session parameters: - $ref: '#/components/parameters/HeaderRequestID' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutSessionRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutSessionResponse' components: parameters: HeaderRequestID: name: Request-Id in: header description: The unique identifier of the request required: true schema: type: string default: 008e3967-a1b5-48bb-be14-d5bff5092e61 schemas: CreateCheckoutSessionRequest: required: - order_id - line_items type: object properties: order_id: type: string description: Third-party order number customer_id: type: string description: >- Subotiz platform customer unique identifier, must be created in Subotiz in advance. One of `payer_id`, `customer_id` and `email` must exist email: type: string description: Customer email line_items: type: array items: $ref: '#/components/schemas/CheckoutSessionLineItem' description: >- Product pricing array included in this checkout (currently only supports one lineItem) return_url: type: string description: >- URL to redirect to after customer payment success. The explicitly provided URL is used first; otherwise, the default from the developer settings is applied automatically. cancel_url: type: string description: >- URL to redirect to after customer cancels payment. The explicitly provided URL is used first; otherwise, the default from the developer settings is applied automatically. mode: type: string description: >- Payment mode, used to determine whether to validate product information: - checkout: Validate product data, default value - payment: Do not validate product data payer_id: type: string description: >- Third-party customer ID, if the passed ID does not exist in the Subotiz system, a customer will be automatically created. Each `payer_id` under each merchant is unique. integration_method: type: string description: |- Integration mode: - hosted: Hosted, default mode - embedded: Embedded integration total_amount: type: string description: Payment amount, required when `mode` is set to payment mode. redirect_on_completion: type: string description: >- Redirect behavior for embedded UI mode - always: Automatically redirect to `return_url` after successful payment - if_required: Only redirect to `return_url` for payment methods that require redirection locale: type: string description: >- Specify the language for the checkout session. The default language is determined based on the browser language. Optional Values： - **ar-SA**：Arabic (Saudi Arabia) - **de-DE**：German (Germany) - **en-US**：English (United States) - **es-ES**：Spanish (Spain) - **fr-FR**：French (France) - **id-ID**：Indonesian (Indonesia) - **it-IT**：Italian (Italy) - **ja-JP**：Japanese (Japan) - **ko-KR**：Korean (South Korea) - **nl-NL**：Dutch (Netherlands) - **pl-PL**：Polish (Poland) - **pt-PT**：Portuguese (Portugal) - **ru-RU**：Russian (Russia) - **th-TH**：Thai (Thailand) - **zh-CN**：Chinese (Mainland China) - **zh-TW**：Chinese (Taiwan, China) target_currency: type: string description: >- Specifies the settlement currency for the Checkout Session using a platform-supported ISO 4217 currency code, such as USD or CNY. The system uses the store's primary currency as the base currency and converts the order amount into this currency for display and pricing. If `merchant_rate` is not provided, the system uses the real-time exchange rate of the day by default. merchant_rate: type: string description: >- Specifies a custom exchange rate from the store's primary currency to `target_currency`. The value must be a number greater than 0 and must be provided together with `target_currency`. This field is used only when the settlement currency differs from the store's primary currency. The exchange rate direction is: "1 unit of the store's primary currency = X units of `target_currency`". For example, if the store's primary currency is USD and `target_currency` is CNY, a value of 7.999 means 1 USD = 7.999 CNY, and the system will calculate the order amount using this rate. metadata: type: object description: >- A set of key-value pairs that can be attached to an object, allowing you to store additional information in a structured format. subscription_data: allOf: - $ref: '#/components/schemas/SubscriptionData' description: >- A subset of parameters to be passed to subscription creation for Checkout Sessions in trade_data: allOf: - $ref: '#/components/schemas/TradeData' description: >- A subset of parameters to be passed to trade creation for Checkout Sessions in source_channel: type: string description: >- First transaction source channel identification, used for transaction attribution statistics, length limit 50 billing_address_data: allOf: - $ref: '#/components/schemas/BillingAddressData' description: Billing address information payment_mode: type: string description: |- Payment business mode: - `onetime_payment`: One-time payment mode. Processes a single payment transaction without creating any recurring payment tokens. - `subscription`: Subscription payment mode. Processes the initial payment and generates a payment token for automatic recurring payments. Subsequent renewal charges will be processed using this token based on the subscription plan configuration. once_trial: type: integer description: |- Whether to enable once free trial period for the trial price. - 1: no trial limit - 2: once trial - 3: skip trial period format: int32 fixed_term: type: integer description: Fixed-term subscription length (positive integer) format: int32 is_renewable: type: boolean description: >- Whether the fixed-term subscription can be converted to a continuous subscription description: Create checkout session request CreateCheckoutSessionResponse: type: object properties: code: type: string description: error code message: type: string description: error message data: $ref: '#/components/schemas/CreateCheckoutSessionResponse_Data' CheckoutSessionLineItem: type: object properties: price_id: type: string description: Unique identifier for product pricing quantity: type: string description: Product quantity description: LineItem structure SubscriptionData: type: object properties: metadata: type: object description: >- A set of key-value pairs that can be attached to an object, allowing you to store additional information in a structured format. TradeData: type: object properties: metadata: type: object description: >- A set of key-value pairs that can be attached to an object, allowing you to store additional information in a structured format. BillingAddressData: type: object properties: name: type: string description: 'Recipient''s full name (e.g: John Smith)' address_line1: type: string description: >- Address line 1, primary street address (e.g: 123 Main Street, Apt 4B) address_line2: type: string description: >- Address line 2, additional address information (e.g: Building C, Floor 5) country_code: type: string description: 'Country code in ISO2 format (e.g: US, GB, CN)' province_code: type: string description: 'Province/state code (e.g: CA for California, ON for Ontario)' city: type: string description: 'City name (e.g: New York, London, Tokyo)' area: type: string description: Area/district/county name for more granular address location postal_code: type: string description: >- Postal code/ZIP code, format varies by country (e.g: US: 12345, UK: SW1A 1AA, CA: K1A 0B1) phone: type: string description: 'Phone number without country code (e.g: 5551234567)' phone_area_code: type: string description: 'Phone country code (e.g: +1, +44, +86)' email: type: string description: >- Email address for billing notifications and contact (e.g: user@example.com) description: Billing address information CreateCheckoutSessionResponse_Data: type: object properties: session_id: type: string description: Checkout Session unique identifier session_url: type: string description: >- Subotiz checkout page URL, customers can be redirected directly to this URL. Only returned for hosted integration mode securitySchemes: sec0: type: http description: >- Bearer API Key authentication. Format: Authorization: Bearer {your_api_key} scheme: bearer ````