Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Subotiz Com Checkout Session API
version: 1.0.0
description: 'Operations tagged Checkout Session across 2 of this provider''s published API definitions: subotiz-com-openapi.yml, v1-en.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{api}.subotiz.com
variables:
api:
default: api
security:
- sec0: []
tags:
- name: Checkout Session
description: 结账会话
paths:
/api/v1/session:
get:
tags:
- Checkout Session
summary: List Checkout Session
operationId: v1-checkout-session-list-checkout-session
parameters:
- name: session_ids
in: query
description: Checkout session ID array, filter checkout sessions whose IDs belong to this array
schema:
type: array
items:
type: string
- name: status
in: query
description: "Checkout session status:\n - open: Created successfully\n - expire: Expired\n - complete: Transaction completed"
schema:
type: string
- name: starting_after
in: query
description: Cursor for pagination. `starting_after` is the object ID that defines your position in the list. For example, if you want to get the next page, you can use the last object's ID as the parameter value after getting the object list for the first time. Cannot be used together with `ending_before`
schema:
type: string
- name: ending_before
in: query
description: Cursor for pagination. `ending_before` is the object ID that defines your position in the list. For example, if you want to get the previous page, you can use the first object's ID as the parameter value after getting the object list for the first time. Cannot be used together with `starting_after`
schema:
type: string
- name: limit
in: query
description: 'Pagination parameter, number of items per page, default: 10, interface defaults to sorting by creation time in descending order. Limit: [1, 100]'
schema:
type: integer
format: int32
- name: order_ids
in: query
description: Third-party order numbers
schema:
type: array
items:
type: string
- name: customer_id
in: query
description: Only return CheckoutSession for the customer that this customer ID specifies.
schema:
type: string
- name: created_at.gt
in: query
description: Minimum value to filter by (exclusive, UTC time in RFC3339 format, such as '2025-01-01T00:00:00Z')
schema:
type: string
- name: created_at.gte
in: query
description: Minimum value to filter by (inclusive, UTC time in RFC3339 format, such as '2025-01-01T00:00:00Z')
schema:
type: string
- name: created_at.lt
in: query
description: Maximum value to filter by (exclusive, UTC time in RFC3339 format, such as '2025-01-01T00:00:00Z')
schema:
type: string
- name: created_at.lte
in: query
description: Maximum value to filter by (inclusive, UTC time in RFC3339 format, such as '2025-01-01T00:00:00Z')
schema:
type: string
- $ref: '#/components/parameters/HeaderRequestID'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListCheckoutSessionResponse'
post:
tags:
- Checkout Session
summary: 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'
servers:
- url: https://{api}.subotiz.com
variables:
api:
default: api
/api/v1/session/{session_id}:
get:
tags:
- Checkout Session
summary: Get Checkout Session
operationId: v1-checkout-session-get-checkout-session
parameters:
- name: session_id
in: path
description: Session ID value
required: true
schema:
type: string
- $ref: '#/components/parameters/HeaderRequestID'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/QuerySessionResponse'
servers:
- url: https://{api}.subotiz.com
variables:
api:
default: api
/api/v1/session/{session_id}/expire:
post:
tags:
- Checkout Session
summary: Expire Checkout Session
description: expire a checkout session.
operationId: v1-checkout-session-expire-checkout-session
parameters:
- name: session_id
in: path
description: Session ID value
required: true
schema:
type: string
- $ref: '#/components/parameters/HeaderRequestID'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ExpireSessionResponse'
servers:
- url: https://{api}.subotiz.com
variables:
api:
default: api
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:
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.
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
QuerySessionResponse:
type: object
properties:
code:
type: string
description: error code
message:
type: string
description: error message
data:
$ref: '#/components/schemas/QuerySessionResponse_Data'
Customer:
type: object
properties:
id:
type: string
description: Customer ID
payer_id:
type: string
description: Third-party customer ID
email:
type: string
description: Customer email
CheckoutLineItem:
type: object
properties:
price_id:
type: string
description: Unique identifier for product pricing
quantity:
type: string
description: Product quantity (number of seats)
quantity_editable:
type: boolean
description: Whether the customer may change the quantity on the checkout page
quantity_min:
type: string
description: Minimum editable quantity. 0 = unlimited (equivalent to the global lower bound of 1). Only meaningful when quantity_editable=true.
quantity_max:
type: string
description: Maximum editable quantity. 0 = unlimited (equivalent to the global upper bound of 999999999). Only meaningful when quantity_editable=true.
merchant_price_id:
type: string
description: Merchant-side price ID, returns the merchant's current configured value; empty string if not configured
description: Product item
CreateCheckoutSessionResponse:
type: object
properties:
code:
type: string
description: error code
message:
type: string
description: error message
data:
$ref: '#/components/schemas/CreateCheckoutSessionResponse_Data'
ListCheckoutSessionResponse_Data:
type: object
properties:
has_more:
type: boolean
description: Whether there is more data
list:
type: array
items:
$ref: '#/components/schemas/CheckoutSession'
description: Checkout session list
QuerySessionResponse_Data:
type: object
properties:
id:
type: string
description: Checkout session ID
access_no:
type: string
description: Third-party access number
merchant_id:
type: string
description: Merchant unique identifier
order_id:
type: string
description: Third-party order number
trade_id:
type: string
description: Trade ID
customer:
allOf:
- $ref: '#/components/schemas/Customer'
description: Customer information
status:
type: string
description: "Checkout session status:\n - open: Created successfully\n - expire: Expired\n - complete: Transaction completed"
expire_time:
type: string
description: Validity period (seconds), expiration time can be calculated by adding validity period to creation time
return_url:
type: string
description: Payment success redirect URL
cancel_url:
type: string
description: Cancel payment redirect URL
callback_url:
type: string
description: Webhook notification URL
session_url:
type: string
description: Checkout page URL
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'
total_amount:
type: string
description: Total amount (excluding discounts and tax)
integration_method:
type: string
description: 'Integration mode:
- hosted: Hosted, default mode
- embedded: Embedded integration'
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'
created_at:
type: string
description: Creation time
payment_token:
type: string
description: Payment token returned for subscription payment, used for subsequent subscription renewals
metadata:
type: object
additionalProperties:
type: string
description: A set of key-value pairs that can be attached to an object, allowing you to store additional information in a structured format.
first_source_channel:
type: string
description: The source where this checkout session was initially created.
last_source_channel:
type: string
description: The source where this checkout session was last accessed.
fixed_term:
type: integer
description: Fixed-term period count
format: int32
is_renewable:
type: boolean
description: Whether it supports conversion to a continuous subscription
tax_amount:
type: string
description: Tax amount
line_items:
type: array
items:
$ref: '#/components/schemas/CheckoutLineItem'
description: Checkout line items
tax_category:
type: string
description: Order tax category. Returned when mode=payment with the value provided by merchant during session creation; otherwise empty.
terms_data:
allOf:
- $ref: '#/components/schemas/TermsData'
description: Terms links supplied when the session was created; omitted when not supplied
powered_by:
allOf:
- $ref: '#/components/schemas/PoweredBy'
description: Powered by configuration supplied when the session was created; omitted when not supplied
ExpireSessionResponse:
type: object
properties:
code:
type: string
description: error code
message:
type: string
description: error message
data:
$ref: '#/components/schemas/ExpireSessionResponse_Data'
description: Expire session response
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
CheckoutSession:
type: object
properties:
id:
type: string
description: Checkout session ID
access_no:
type: string
description: Third-party access number
merchant_id:
type: string
description: Merchant unique identifier
order_id:
type: string
description: Third-party order number
trade_id:
type: string
description: Trade ID
customer:
allOf:
- $ref: '#/components/schemas/Customer'
description: Customer information
status:
type: string
description: "Checkout session status:\n - open: Created successfully\n - expire: Expired\n - complete: Transaction completed"
expire_time:
type: string
description: Validity period (seconds), expiration time can be calculated by adding validity period to creation time
return_url:
type: string
description: Payment success redirect URL
cancel_url:
type: string
description: Cancel payment redirect URL
callback_url:
type: string
description: Webhook notification URL
session_url:
type: string
description: Checkout page URL
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'
total_amount:
type: string
description: Total amount (excluding discounts and tax)
integration_method:
type: string
description: 'Integration mode:
- hosted: Hosted, default mode
- embedded: Embedded integration'
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'
created_at:
type: string
description: Creation time
payment_token:
type: string
description: Payment token returned for subscription payment, used for subsequent subscription renewals
metadata:
type: object
additionalProperties:
type: string
description: A set of key-value pairs that can be attached to an object, allowing you to store additional information in a structured format.
first_source_channel:
type: string
description: The source where this checkout session was initially created.
last_source_channel:
type: string
description: The source where this checkout session was last accessed.
fixed_term:
type: integer
description: Fixed-term subscription length
format: int32
is_renewable:
type: boolean
description: Whether it can be converted to a continuous subscription
line_items:
type: array
items:
$ref: '#/components/schemas/CheckoutLineItem'
description: Checkout line items
tax_category:
type: string
description: Order tax category. Returned when mode=payment with the value provided by merchant during session creation; otherwise empty.
terms_data:
allOf:
- $ref: '#/components/schemas/TermsData'
description: Terms links supplied when the session was created; omitted when not supplied
powered_by:
allOf:
- $ref: '#/components/schemas/PoweredBy'
description: Powered by configuration supplied when the session was created; omitted when not supplied
ExpireSessionResponse_Data:
type: object
properties:
id:
type: string
description: Checkout session ID
status:
type: string
description: "Checkout session status:\n - open: Created successfully\n - lock: Locked\n - expire: Expired\n - complete: Transaction completed"
description: Expire session response
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.
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
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
ListCheckoutSessionResponse:
type: object
properties:
code:
type: string
description: error code
message:
type: string
description: error message
data:
$ref: '#/components/schemas/ListCheckoutSessionResponse_Data'
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:\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.
- `Software`: Downloadable or licensed standalone software that typically requires local installation (e.g. installers, license keys).
- `Online Video Content`: Video content delivered via streaming or download (e.g. courses, movies, live streams).
- `Information Service`: Digital data or reports (e.g. databases, industry reports, analytics).
- `eBook`: Electronic books or digital publications readable on devices.
- `Digital Graphic / Template`: Editable digital templates or design assets (e.g. PSD/templates, PowerPoint templates).
- `Video Game`: Digital games, including downloads, in-app purchases, or subscription services.
- `Blockchain Digital Products`: Blockchain-based digital assets (e.g. NFTs).
- `Other Digital Products`: Other virtual goods not covered above (e.g. event tickets).'
terms_data:
allOf:
- $ref: '#/components/schemas/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: '#/components/schemas/PoweredBy'
description: Powered by branding shown at the bottom of the checkout page; optional. Defaults to showing Subotiz when omitted
description: Create checkout session request
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
x-refined-from:
- subotiz-com-openapi.yml
- v1-en.yaml