CreateCheckoutSessionRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/subotiz-com/json-schema/subotiz-com-create-checkout-session-request-schema.json",
  "title": "CreateCheckoutSessionRequest",
  "description": "Create checkout session request",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/subotiz-com-openapi.yml#/components/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": "#/$defs/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:\n- checkout: Validate product data, default value\n- 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:\n- hosted: Hosted, default mode\n- 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\n- always: Automatically redirect to `return_url` after successful payment\n- 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.\nOptional Values：\n- **ar-SA**：Arabic (Saudi Arabia)\n- **de-DE**：German (Germany)\n- **en-US**：English (United States)\n- **es-ES**：Spanish (Spain)\n- **fr-FR**：French (France)\n- **id-ID**：Indonesian (Indonesia)\n- **it-IT**：Italian (Italy)\n- **ja-JP**：Japanese (Japan)\n- **ko-KR**：Korean (South Korea)\n- **nl-NL**：Dutch (Netherlands)\n- **pl-PL**：Polish (Poland)\n- **pt-PT**：Portuguese (Portugal)\n- **ru-RU**：Russian (Russia)\n- **th-TH**：Thai (Thailand)\n- **zh-CN**：Chinese (Mainland China)\n- **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": "#/$defs/SubscriptionData"
        }
      ],
      "description": "A subset of parameters to be passed to subscription creation for Checkout Sessions in"
    },
    "trade_data": {
      "allOf": [
        {
          "$ref": "#/$defs/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": "#/$defs/BillingAddressData"
        }
      ],
      "description": "Billing address information"
    },
    "payment_mode": {
      "type": "string",
      "description": "Payment business mode:\n - `onetime_payment`: One-time payment mode. Processes a single payment transaction without creating any recurring payment tokens.\n - `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.\n - 1: no trial limit\n - 2: once trial\n - 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"
    },
    "tax_category": {
      "type": "string",
      "description": "- `Software as a service (SaaS)`: Software delivered over the internet as a subscription, no local installation required.\n- `Software`: Downloadable or licensed standalone software that typically requires local installation (e.g. installers, license keys).\n- `Online Video Content`: Video content delivered via streaming or download (e.g. courses, movies, live streams).\n- `Information Service`: Digital data or reports (e.g. databases, industry reports, analytics).\n- `eBook`: Electronic books or digital publications readable on devices.\n- `Digital Graphic / Template`: Editable digital templates or design assets (e.g. PSD/templates, PowerPoint templates).\n- `Video Game`: Digital games, including downloads, in-app purchases, or subscription services.\n- `Blockchain Digital Products`: Blockchain-based digital assets (e.g. NFTs).\n- `Other Digital Products`: Other virtual goods not covered above (e.g. event tickets)."
    },
    "terms_data": {
      "allOf": [
        {
          "$ref": "#/$defs/TermsData"
        }
      ],
      "description": "TermsData: merchant-provided terms links displayed on checkout; optional. Each URL may be empty.\n Must be an absolute https URL and length <= 512, otherwise 400"
    },
    "powered_by": {
      "allOf": [
        {
          "$ref": "#/$defs/PoweredBy"
        }
      ],
      "description": "Powered by branding shown at the bottom of the checkout page; optional. Defaults to showing Subotiz when omitted"
    }
  },
  "$defs": {
    "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"
    },
    "CheckoutSessionLineItem": {
      "type": "object",
      "properties": {
        "price_id": {
          "type": "string",
          "description": "Unique identifier for product pricing"
        },
        "quantity": {
          "type": "string",
          "description": "Product quantity"
        },
        "quantity_editable": {
          "type": "boolean",
          "description": "Whether the customer may change the quantity on the checkout page. Omitted/false = not editable."
        },
        "quantity_min": {
          "type": "string",
          "description": "Minimum editable quantity. 0 or omitted = unlimited (falls back to the global lower bound of 1). Only takes effect when quantity_editable=true."
        },
        "quantity_max": {
          "type": "string",
          "description": "Maximum editable quantity. 0 or omitted = unlimited (falls back to the global upper bound of 999999999). Only takes effect when quantity_editable=true."
        }
      },
      "description": "LineItem structure"
    },
    "PoweredBy": {
      "type": "object",
      "properties": {
        "visible": {
          "type": "boolean",
          "description": "Whether to show Powered by; defaults to true when omitted. When false, brand_name / brand_logo_url have no effect"
        },
        "brand_name": {
          "type": "string",
          "description": "Brand text, optional. Leading and trailing whitespace is trimmed, and whitespace-only is treated as omitted. Length must be <= 20 and must not contain control or format characters (e.g. zero-width, RTL override), otherwise 400.\n When brand_logo_url is also provided, it serves as the logo's alt text and is shown if the logo fails to load"
        },
        "brand_logo_url": {
          "type": "string",
          "description": "Brand logo URL, optional. Must be an absolute https URL and length <= 512, otherwise 400.\n Loaded directly by the checkout page without re-hosting; it must be publicly accessible"
        }
      },
      "description": "PoweredBy configures the \"Powered by\" branding shown at the bottom of the checkout page"
    },
    "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."
        }
      }
    },
    "TermsData": {
      "type": "object",
      "properties": {
        "terms_url": {
          "type": "string"
        },
        "privacy_url": {
          "type": "string"
        }
      },
      "description": "TermsData carries the merchant's own terms links shown on the checkout page"
    },
    "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."
        }
      }
    }
  }
}