> ## Documentation Index > Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt > Use this file to discover all available pages before exploring further. # 预览结账会话 > 预览结账会话以计算定价、税费和总额，而无需创建实际会话。 ## OpenAPI ````yaml post /checkouts/preview openapi: 3.1.0 info: title: public description: '' license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: 1.105.11 servers: - url: https://test.dodopayments.com/ description: Test Mode Server Host - url: https://live.dodopayments.com/ description: Live Mode Server Host security: [] tags: - name: Products - name: Payments - name: Subscriptions - name: Addons - name: Customers - name: Refunds - name: Disputes - name: Events - name: License Keys - name: Entitlements - name: Licenses - name: Discounts - name: Meters - name: Credit Entitlements - name: Credit Entitlement Balances - name: Outgoing Webhooks - name: Checkout - name: Webhook Events paths: /checkouts/preview: post: tags: - Checkout Sessions operationId: preview_session requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutSessionRequest' required: true responses: '200': description: Checkout session preview calculated successfully content: application/json: schema: $ref: '#/components/schemas/CalculateSessionResponse' '422': description: Invalid Request Object or Parameters '500': description: Something went wrong :( security: - API_KEY: [] x-codeSamples: - lang: JavaScript source: |- import DodoPayments from 'dodopayments'; const client = new DodoPayments({ bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted }); const response = await client.checkoutSessions.preview({ product_cart: [{ product_id: 'product_id', quantity: 0 }], }); console.log(response.tax_id_business_name); - lang: Python source: |- import os from dodopayments import DodoPayments client = DodoPayments( bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"), # This is the default and can be omitted ) response = client.checkout_sessions.preview( product_cart=[{ "product_id": "product_id", "quantity": 0, }], ) print(response.tax_id_business_name) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/dodopayments/dodopayments-go\"\n\t\"github.com/dodopayments/dodopayments-go/option\"\n)\n\nfunc main() {\n\tclient := dodopayments.NewClient(\n\t\toption.WithBearerToken(\"My Bearer Token\"),\n\t)\n\tresponse, err := client.CheckoutSessions.Preview(context.TODO(), dodopayments.CheckoutSessionPreviewParams{\n\t\tCheckoutSessionRequest: dodopayments.CheckoutSessionRequestParam{\n\t\t\tProductCart: dodopayments.F([]dodopayments.ProductItemReqParam{{\n\t\t\t\tProductID: dodopayments.F(\"product_id\"),\n\t\t\t\tQuantity: dodopayments.F(int64(0)),\n\t\t\t}}),\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.TaxIDBusinessName)\n}\n" - lang: Java source: >- package com.dodopayments.api.example; import com.dodopayments.api.client.DodoPaymentsClient; import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient; import com.dodopayments.api.models.checkoutsessions.CheckoutSessionPreviewResponse; import com.dodopayments.api.models.checkoutsessions.CheckoutSessionRequest; import com.dodopayments.api.models.checkoutsessions.ProductItemReq; public final class Main { private Main() {} public static void main(String[] args) { DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv(); CheckoutSessionRequest params = CheckoutSessionRequest.builder() .addProductCart(ProductItemReq.builder() .productId("product_id") .quantity(0) .build()) .build(); CheckoutSessionPreviewResponse response = client.checkoutSessions().preview(params); } } - lang: Kotlin source: >- package com.dodopayments.api.example import com.dodopayments.api.client.DodoPaymentsClient import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient import com.dodopayments.api.models.checkoutsessions.CheckoutSessionPreviewResponse import com.dodopayments.api.models.checkoutsessions.CheckoutSessionRequest import com.dodopayments.api.models.checkoutsessions.ProductItemReq fun main() { val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv() val params: CheckoutSessionRequest = CheckoutSessionRequest.builder() .addProductCart(ProductItemReq.builder() .productId("product_id") .quantity(0) .build()) .build() val response: CheckoutSessionPreviewResponse = client.checkoutSessions().preview(params) } - lang: Ruby source: >- require "dodopayments" dodo_payments = Dodopayments::Client.new( bearer_token: "My Bearer Token", environment: "test_mode" # defaults to "live_mode" ) response = dodo_payments.checkout_sessions.preview(product_cart: [{product_id: "product_id", quantity: 0}]) puts(response) - lang: PHP source: |- checkoutSessions->preview( productCart: [ [ 'productID' => 'product_id', 'quantity' => 0, 'addons' => [['addonID' => 'addon_id', 'quantity' => 0]], 'amount' => 0, 'creditEntitlements' => [ [ 'creditEntitlementID' => 'credit_entitlement_id', 'creditsAmount' => 'credits_amount', ], ], ], ], allowedPaymentMethodTypes: [PaymentMethodTypes::ACH], billingAddress: [ 'country' => CountryCode::AF, 'city' => 'city', 'state' => 'state', 'street' => 'street', 'zipcode' => 'zipcode', ], billingCurrency: Currency::AED, cancelURL: 'cancel_url', confirm: true, customFields: [ [ 'fieldType' => 'text', 'key' => 'key', 'label' => 'label', 'options' => ['string'], 'placeholder' => 'placeholder', 'required' => true, ], ], customer: ['customerID' => 'customer_id'], customerBusinessName: 'customer_business_name', customization: [ 'forceLanguage' => 'force_language', 'showOnDemandTag' => true, 'showOrderDetails' => true, 'theme' => 'dark', 'themeConfig' => [ 'dark' => [ 'bgPrimary' => 'bg_primary', 'bgSecondary' => 'bg_secondary', 'borderPrimary' => 'border_primary', 'borderSecondary' => 'border_secondary', 'buttonPrimary' => 'button_primary', 'buttonPrimaryHover' => 'button_primary_hover', 'buttonSecondary' => 'button_secondary', 'buttonSecondaryHover' => 'button_secondary_hover', 'buttonTextPrimary' => 'button_text_primary', 'buttonTextSecondary' => 'button_text_secondary', 'inputFocusBorder' => 'input_focus_border', 'textError' => 'text_error', 'textPlaceholder' => 'text_placeholder', 'textPrimary' => 'text_primary', 'textSecondary' => 'text_secondary', 'textSuccess' => 'text_success', ], 'fontPrimaryURL' => 'font_primary_url', 'fontSecondaryURL' => 'font_secondary_url', 'fontSize' => 'xs', 'fontWeight' => 'normal', 'light' => [ 'bgPrimary' => 'bg_primary', 'bgSecondary' => 'bg_secondary', 'borderPrimary' => 'border_primary', 'borderSecondary' => 'border_secondary', 'buttonPrimary' => 'button_primary', 'buttonPrimaryHover' => 'button_primary_hover', 'buttonSecondary' => 'button_secondary', 'buttonSecondaryHover' => 'button_secondary_hover', 'buttonTextPrimary' => 'button_text_primary', 'buttonTextSecondary' => 'button_text_secondary', 'inputFocusBorder' => 'input_focus_border', 'textError' => 'text_error', 'textPlaceholder' => 'text_placeholder', 'textPrimary' => 'text_primary', 'textSecondary' => 'text_secondary', 'textSuccess' => 'text_success', ], 'payButtonText' => 'pay_button_text', 'radius' => 'radius', ], ], discountCode: 'discount_code', discountCodes: ['string'], featureFlags: [ 'allowCurrencySelection' => true, 'allowCustomerEditingBusinessName' => true, 'allowCustomerEditingCity' => true, 'allowCustomerEditingCountry' => true, 'allowCustomerEditingEmail' => true, 'allowCustomerEditingName' => true, 'allowCustomerEditingState' => true, 'allowCustomerEditingStreet' => true, 'allowCustomerEditingTaxID' => true, 'allowCustomerEditingZipcode' => true, 'allowDiscountCode' => true, 'allowPhoneNumberCollection' => true, 'allowTaxID' => true, 'alwaysCreateNewCustomer' => true, 'redirectImmediately' => true, 'requirePhoneNumber' => true, ], force3DS: true, mandateMinAmountInrPaise: 0, metadata: ['foo' => 'string'], minimalAddress: true, paymentMethodID: 'payment_method_id', productCollectionID: 'product_collection_id', returnURL: 'return_url', shortLink: true, showSavedPaymentMethods: true, subscriptionData: [ 'onDemand' => [ 'mandateOnly' => true, 'adaptiveCurrencyFeesInclusive' => true, 'productCurrency' => Currency::AED, 'productDescription' => 'product_description', 'productPrice' => 0, ], 'trialPeriodDays' => 0, ], taxID: 'tax_id', ); var_dump($response); } catch (APIException $e) { echo $e->getMessage(); } - lang: C# source: |- using System; using DodoPayments.Client; using DodoPayments.Client.Models.CheckoutSessions; DodoPaymentsClient client = new(); CheckoutSessionPreviewParams parameters = new() { ProductCart = [ new() { ProductID = "product_id", Quantity = 0, Addons = [ new() { AddonID = "addon_id", Quantity = 0, }, ], Amount = 0, CreditEntitlements = [ new() { CreditEntitlementID = "credit_entitlement_id", CreditsAmount = "credits_amount", }, ], }, ], }; var response = await client.CheckoutSessions.Preview(parameters); Console.WriteLine(response); - lang: Rust source: |- use dodopayments::Client; #[tokio::main] async fn main() -> dodopayments::Result<()> { let client = Client::from_env()?; let result = client .checkout_sessions() .preview() .body(dodopayments::models::CheckoutSessionsCreateParams { product_cart: Some(vec![dodopayments::models::ProductItemReq { product_id: "product_id".to_string(), quantity: 0, addons: None, amount: None, credit_entitlements: None, }]), ..Default::default() }) .await?; println!("{result:?}"); Ok(()) } components: schemas: CreateCheckoutSessionRequest: type: object required: - product_cart properties: allowed_payment_method_types: type: - array - 'null' items: $ref: '#/components/schemas/PaymentMethodTypes' description: >- Customers will never see payment methods that are not in this list. However, adding a method here does not guarantee customers will see it. Availability still depends on other factors (e.g., customer location, merchant settings). Disclaimar: Always provide 'credit' and 'debit' as a fallback. If all payment methods are unavailable, checkout session will fail. uniqueItems: true billing_address: oneOf: - type: 'null' - $ref: '#/components/schemas/CheckoutSessionBillingAddress' description: Billing address information for the session billing_currency: oneOf: - type: 'null' - $ref: '#/components/schemas/Currency' description: This field is ingored if adaptive pricing is disabled cancel_url: type: - string - 'null' description: >- The URL to redirect the customer if they cancel or go back from the checkout. If not provided, the back button will not be displayed. confirm: type: boolean description: >- If confirm is true, all the details will be finalized. If required data is missing, an API error is thrown. custom_fields: oneOf: - type: 'null' - $ref: '#/components/schemas/CustomFields' description: >- Custom fields to collect from customer during checkout (max 5 fields) customer: oneOf: - type: 'null' - $ref: '#/components/schemas/CustomerRequest' description: Customer details for the session customer_business_name: type: - string - 'null' description: >- Optional business / legal name associated with the tax id. When provided together with a valid tax id for a B2B purchase, this name is rendered on the invoice instead of the customer's personal name. customization: $ref: '#/components/schemas/CheckoutSessionCustomization' description: Customization for the checkout session page discount_code: type: - string - 'null' description: >- DEPRECATED: Use discount_codes instead. Cannot be used together with discount_codes. deprecated: true x-stainless-deprecation-message: Use `discount_id` instead. discount_codes: type: - array - 'null' items: type: string description: |- Stacked discount codes to apply, in order. Max 20. Cannot be used together with discount_code. feature_flags: $ref: '#/components/schemas/CheckoutSessionFlags' force_3ds: type: - boolean - 'null' description: Override merchant default 3DS behaviour for this session mandate_min_amount_inr_paise: type: - integer - 'null' format: int32 description: >- Override the merchant-level mandate floor (in INR paise) for INR e-mandates on Indian-card recurring payments. The mandate amount sent to the processor is `max(this_floor, actual_billing_amount)`, so this is effectively the customer-facing authorization ceiling whenever billing is lower. When unset, the merchant setting applies; when that's also unset, the system default of ₹15,000 applies. metadata: oneOf: - type: 'null' - $ref: '#/components/schemas/Metadata' description: >- Additional metadata associated with the payment. Defaults to empty if not provided. minimal_address: type: boolean description: >- If true, only zipcode is required when confirm is true; other address fields remain optional payment_method_id: type: - string - 'null' description: |- Optional payment method ID to use for this checkout session. Only allowed when `confirm` is true. If provided, existing customer id must also be provided. product_cart: type: array items: $ref: '#/components/schemas/ProductItemReq' product_collection_id: type: - string - 'null' description: Product collection ID for collection-based checkout flow return_url: type: - string - 'null' description: The url to redirect after payment failure or success. short_link: type: boolean description: |- If true, returns a shortened checkout URL. Defaults to false if not specified. show_saved_payment_methods: type: boolean description: >- Display saved payment methods of a returning customer False by default subscription_data: oneOf: - type: 'null' - $ref: '#/components/schemas/SubscriptionData' tax_id: type: - string - 'null' description: >- Tax ID for the customer (e.g. VAT number). Requires billing_address with country. CalculateSessionResponse: type: object description: Data returned by the calculate checkout session API required: - total_price - currency - product_cart - current_breakup - billing_country - is_byop properties: billing_country: $ref: '#/components/schemas/CountryCodeAlpha2' description: Billing country currency: $ref: '#/components/schemas/Currency' description: Currency in which the calculations were made current_breakup: $ref: '#/components/schemas/CurrentBreakup' description: Breakup of the current payment is_byop: type: boolean description: |- Whether the payment will be routed through the merchant's own processor (BYOP). True when the session's business has a BYOP route configured for the billing country; in that case the quoted amounts exclude Dodo-computed tax because the merchant is MoR and owns tax. product_cart: type: array items: $ref: '#/components/schemas/CalculatedProductCartItem' description: The total product cart recurring_breakup: oneOf: - type: 'null' - $ref: '#/components/schemas/RecurringBreakup' description: Breakup of recurring payments (None for one-time only) tax_id_business_name: type: - string - 'null' description: >- Registered business name from the official registry (EU/GB/AU) when found tax_id_err_msg: type: - string - 'null' description: Error message if tax ID validation failed tax_id_format_name: type: - string - 'null' description: The matched tax ID notation (e.g. "VAT Number", "GSTIN") when valid total_price: type: integer format: int32 description: Total calculate price of the product cart minimum: 0 total_tax: type: - integer - 'null' format: int32 description: Total tax minimum: 0 PaymentMethodTypes: type: string description: |- All supported payment method types. Used for disabled-payment-methods filtering and validation. enum: - ach - affirm - afterpay_clearpay - alfamart - ali_pay - ali_pay_hk - alma - amazon_pay - apple_pay - atome - bacs - bancontact_card - becs - benefit - bizum - blik - boleto - bca_bank_transfer - bni_va - bri_va - card_redirect - cimb_va - classic - credit - crypto_currency - cashapp - dana - danamon_va - debit - duit_now - efecty - eft - eps - fps - evoucher - giropay - givex - google_pay - go_pay - gcash - ideal - interac - indomaret - klarna - kakao_pay - local_bank_redirect - mandiri_va - knet - mb_way - mobile_pay - momo - momo_atm - multibanco - online_banking_thailand - online_banking_czech_republic - online_banking_finland - online_banking_fpx - online_banking_poland - online_banking_slovakia - oxxo - pago_efectivo - permata_bank_transfer - open_banking_uk - pay_bright - paypal - paze - pix - pay_safe_card - przelewy24 - prompt_pay - pse - red_compra - red_pagos - samsung_pay - sepa - sepa_bank_transfer - sofort - sunbit - swish - touch_n_go - trustly - twint - upi_collect - upi_intent - vipps - viet_qr - venmo - walley - we_chat_pay - seven_eleven - lawson - mini_stop - family_mart - seicomart - pay_easy - local_bank_transfer - mifinity - open_banking_pis - direct_carrier_billing - instant_bank_transfer - billie - zip - revolut_pay - naver_pay - payco - satispay CheckoutSessionBillingAddress: type: object title: Checkout Session Billing Address required: - country properties: city: type: - string - 'null' description: City name country: $ref: '#/components/schemas/CountryCodeAlpha2' description: Two-letter ISO country code (ISO 3166-1 alpha-2) state: type: - string - 'null' description: State or province name street: type: - string - 'null' description: >- Street address including house number and unit/apartment if applicable zipcode: type: - string - 'null' description: Postal code or ZIP code Currency: type: string enum: - AED - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BWP - BYN - BZD - CAD - CHF - CLP - CNY - COP - CRC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - JMD - JOD - JPY - KES - KGS - KHR - KMF - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SEK - SGD - SHP - SLE - SLL - SOS - SRD - SSP - STN - SVC - SZL - THB - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW CustomFields: type: array items: $ref: '#/components/schemas/CustomField' description: Wrapper for custom fields with validation CustomerRequest: oneOf: - $ref: '#/components/schemas/AttachExistingCustomer' - $ref: '#/components/schemas/NewCustomer' title: Customer Request CheckoutSessionCustomization: type: object title: Checkout Session Customization properties: force_language: type: - string - 'null' description: >- Force the checkout interface to render in a specific language (e.g. `en`, `es`) show_on_demand_tag: type: boolean description: |- Show on demand tag Default is true show_order_details: type: boolean description: |- Show order details by default Default is true theme: oneOf: - type: 'null' - $ref: '#/components/schemas/ThemeMode' description: >- Theme of the page (determines which mode - light/dark/system - to use) If not provided, uses the business-configured theme from business_themes table. theme_config: oneOf: - type: 'null' - $ref: '#/components/schemas/ThemeConfig' description: >- Optional custom theme configuration with colors for light and dark modes CheckoutSessionFlags: type: object title: Checkout Session Flags properties: allow_currency_selection: type: boolean description: |- if customer is allowed to change currency, set it to true Default is true allow_customer_editing_business_name: type: boolean description: >- If true, the customer can supply or edit the business name associated with the tax id during checkout. Works independently of `allow_customer_editing_tax_id` — either flag (or `allow_tax_id`) is sufficient to let the customer override the session's business name. Typically set together with `allow_customer_editing_tax_id`. Default is false allow_customer_editing_city: type: boolean allow_customer_editing_country: type: boolean allow_customer_editing_email: type: boolean allow_customer_editing_name: type: boolean allow_customer_editing_state: type: boolean allow_customer_editing_street: type: boolean allow_customer_editing_tax_id: type: boolean allow_customer_editing_zipcode: type: boolean allow_discount_code: type: boolean description: |- If the customer is allowed to apply discount code, set it to true. Default is true allow_phone_number_collection: type: boolean description: |- If phone number is collected from customer, set it to rue Default is true allow_tax_id: type: boolean description: |- If the customer is allowed to add tax id, set it to true Default is true always_create_new_customer: type: boolean description: >- Set to true if a new customer object should be created. By default email is used to find an existing customer to attach the session to Default is false redirect_immediately: type: boolean description: |- If true, redirects the customer immediately after payment completion Default is false require_phone_number: type: boolean description: >- If true, the customer must provide a phone number to complete checkout. Requires `allow_phone_number_collection` to also be true. Default is false Metadata: type: object additionalProperties: type: string propertyNames: type: string ProductItemReq: type: object title: Product Item Request required: - product_id - quantity properties: addons: type: - array - 'null' items: $ref: '#/components/schemas/AttachAddonReq' description: only valid if product is a subscription amount: type: - integer - 'null' format: int32 description: >- Amount the customer pays if pay_what_you_want is enabled. If disabled then amount will be ignored Represented in the lowest denomination of the currency (e.g., cents for USD). For example, to charge $1.00, pass `100`. Only applicable for one time payments If amount is not set for pay_what_you_want product, customer is allowed to select the amount. credit_entitlements: type: - array - 'null' items: $ref: '#/components/schemas/CreditEntitlementOverride' description: >- Per-checkout-session overrides for credit entitlements already attached to this product. Each entry overrides the `credits_amount` granted by the referenced credit entitlement when this checkout session is fulfilled. The credit_entitlement_id must already be attached to the product. product_id: type: string description: unique id of the product quantity: type: integer format: int32 minimum: 0 SubscriptionData: type: object title: Subscription Data properties: on_demand: oneOf: - type: 'null' - $ref: '#/components/schemas/OnDemandSubscriptionReq' trial_period_days: type: - integer - 'null' format: int32 description: >- Optional trial period in days If specified, this value overrides the trial period set in the product's price Must be between 0 and 10000 days CountryCodeAlpha2: type: string description: ISO country code alpha2 variant enum: - AF - AX - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MK - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SZ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - UM - US - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW CurrentBreakup: type: object description: Breakup of the current (first) payment required: - total_amount - subtotal - discount properties: discount: type: integer format: int32 description: Total discount amount minimum: 0 subtotal: type: integer format: int32 description: Subtotal before discount (pre-tax original prices) minimum: 0 tax: type: - integer - 'null' format: int32 description: Total tax amount minimum: 0 total_amount: type: integer format: int32 description: Total amount to be charged (final amount after all calculations) minimum: 0 CalculatedProductCartItem: type: object required: - product_id - quantity - discounted_price - og_price - currency - og_currency - tax_rate - tax_category - meters - is_usage_based - tax_inclusive - is_subscription - credit_entitlements properties: addons: type: - array - 'null' items: $ref: '#/components/schemas/CalculatedAddonItem' credit_entitlements: type: array items: $ref: '#/components/schemas/CheckoutCreditEntitlementItem' description: Credit entitlements that will be granted upon purchase currency: $ref: '#/components/schemas/Currency' description: the currency in which the calculatiosn were made description: type: - string - 'null' discount_amount: type: - integer - 'null' format: int32 description: discount percentage discount_cycle: type: - integer - 'null' format: int32 description: number of cycles the discount will apply discounted_price: type: integer format: int32 description: discounted price minimum: 0 is_subscription: type: boolean description: >- Whether this is a subscription product (affects tax calculation in breakup) is_usage_based: type: boolean meters: type: array items: $ref: '#/components/schemas/MeterDetails' name: type: - string - 'null' description: name of the product og_currency: $ref: '#/components/schemas/Currency' description: the product currency og_price: type: integer format: int32 description: original price of the product minimum: 0 product_id: type: string description: unique id of the product quantity: type: integer format: int32 description: Quanitity minimum: 0 tax: type: - integer - 'null' format: int32 description: total tax tax_category: $ref: '#/components/schemas/TaxCategory' description: tax category tax_inclusive: type: boolean description: Whether tax is included in the price tax_rate: type: integer format: int32 description: tax rate RecurringBreakup: type: object description: Breakup of recurring payments (subscription only) required: - total_amount - subtotal - discount properties: discount: type: integer format: int32 description: Total discount amount minimum: 0 subtotal: type: integer format: int32 description: Subtotal before discount (pre-tax original prices) minimum: 0 tax: type: - integer - 'null' format: int32 description: Total tax on recurring payments minimum: 0 total_amount: type: integer format: int32 description: Total recurring amount including tax minimum: 0 CustomField: type: object description: Definition of a custom field for checkout required: - key - label - field_type properties: field_type: $ref: '#/components/schemas/CustomFieldType' description: Type of field determining validation rules key: type: string description: Unique identifier for this field (used as key in responses) label: type: string description: Display label shown to customer options: type: - array - 'null' items: type: string description: >- Options for dropdown type (required for dropdown, ignored for others) placeholder: type: - string - 'null' description: Placeholder text for the input required: type: boolean description: Whether this field is required AttachExistingCustomer: type: object title: Attach Existing Customer required: - customer_id properties: customer_id: type: string NewCustomer: type: object title: New Customer required: - email properties: email: type: string description: Email is required for creating a new customer name: type: - string - 'null' description: >- Optional full name of the customer. If provided during session creation, it is persisted and becomes immutable for the session. If omitted here, it can be provided later via the confirm API. phone_number: type: - string - 'null' ThemeMode: type: string enum: - dark - light - system ThemeConfig: type: object description: Custom theme configuration with colors for light and dark modes. properties: dark: oneOf: - type: 'null' - $ref: '#/components/schemas/ThemeModeConfig' description: Dark mode color configuration font_primary_url: type: - string - 'null' description: URL for the primary font. Must be a valid https:// URL. font_secondary_url: type: - string - 'null' description: URL for the secondary font. Must be a valid https:// URL. font_size: oneOf: - type: 'null' - $ref: '#/components/schemas/FontSize' description: Font size for the checkout UI font_weight: oneOf: - type: 'null' - $ref: '#/components/schemas/FontWeight' description: Font weight for the checkout UI light: oneOf: - type: 'null' - $ref: '#/components/schemas/ThemeModeConfig' description: Light mode color configuration pay_button_text: type: - string - 'null' description: >- Custom text for the pay button (e.g., "Complete Purchase", "Subscribe Now"). Max 100 characters. radius: type: - string - 'null' description: >- Border radius for UI elements. Must be a number followed by px, rem, or em (e.g., "4px", "0.5rem", "1em") AttachAddonReq: type: object title: Attach Addon Request required: - addon_id - quantity properties: addon_id: type: string quantity: type: integer format: int32 minimum: 0 CreditEntitlementOverride: type: object description: >- Per-checkout-session override for a single credit entitlement attached to a product. required: - credit_entitlement_id - credits_amount properties: credit_entitlement_id: type: string description: >- ID of the credit entitlement to override. Must already be attached to the product. credits_amount: type: string description: >- Number of credits to grant for this checkout session, overriding the product-level `credits_amount` set on the credit entitlement mapping. Must be greater than zero. OnDemandSubscriptionReq: type: object title: On Demand Subscription Request required: - mandate_only properties: adaptive_currency_fees_inclusive: type: - boolean - 'null' description: >- Whether adaptive currency fees should be included in the product_price (true) or added on top (false). This field is ignored if adaptive pricing is not enabled for the business. mandate_only: type: boolean description: >- If set as True, does not perform any charge and only authorizes payment method details for future use. product_currency: oneOf: - type: 'null' - $ref: '#/components/schemas/Currency' description: >- Optional currency of the product price. If not specified, defaults to the currency of the product. product_description: type: - string - 'null' description: >- Optional product description override for billing and line items. If not specified, the stored description of the product will be used. product_price: type: - integer - 'null' format: int32 description: >- Product price for the initial charge to customer If not specified the stored price of the product will be used Represented in the lowest denomination of the currency (e.g., cents for USD). For example, to charge $1.00, pass `100`. CalculatedAddonItem: type: object required: - addon_id - quantity - name - og_price - discounted_price - og_currency - currency - tax_category - tax_inclusive - tax_rate properties: addon_id: type: string currency: $ref: '#/components/schemas/Currency' description: type: - string - 'null' discount_amount: type: - integer - 'null' format: int32 discounted_price: type: integer format: int32 minimum: 0 name: type: string og_currency: $ref: '#/components/schemas/Currency' og_price: type: integer format: int32 minimum: 0 quantity: type: integer format: int32 minimum: 0 tax: type: - integer - 'null' format: int32 tax_category: $ref: '#/components/schemas/TaxCategory' tax_inclusive: type: boolean tax_rate: type: integer format: int32 CheckoutCreditEntitlementItem: type: object description: >- Minimal credit entitlement info shown at checkout — what credits the customer will receive required: - credit_entitlement_id - credit_entitlement_name - credit_entitlement_unit - credits_amount properties: credit_entitlement_id: type: string description: ID of the credit entitlement credit_entitlement_name: type: string description: Name of the credit entitlement credit_entitlement_unit: type: string description: Unit label (e.g. "API Calls", "Tokens") credits_amount: type: string description: Number of credits granted MeterDetails: type: object required: - price_per_unit - name - measurement_unit properties: description: type: - string - 'null' free_threshold: type: - integer - 'null' format: int64 measurement_unit: type: string name: type: string price_per_unit: type: string example: '10.50' TaxCategory: type: string description: >- Represents the different categories of taxation applicable to various products and services. enum: - digital_products - saas - e_book - edtech CustomFieldType: type: string description: Custom field type for checkout forms enum: - text - number - email - url - date - dropdown - boolean ThemeModeConfig: type: object description: |- Color configuration for a single theme mode (light or dark). All color fields accept standard CSS color formats: - Hex: `#fff`, `#ffffff`, `#ffffffff` (with or without # prefix) - RGB/RGBA: `rgb(255, 255, 255)`, `rgba(255, 255, 255, 0.5)` - HSL/HSLA: `hsl(120, 100%, 50%)`, `hsla(120, 100%, 50%, 0.5)` - Named colors: `red`, `blue`, `transparent`, etc. - Advanced: `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, `color()` properties: bg_primary: type: - string - 'null' description: |- Background primary color Examples: `"#ffffff"`, `"rgb(255, 255, 255)"`, `"white"` bg_secondary: type: - string - 'null' description: Background secondary color border_primary: type: - string - 'null' description: Border primary color border_secondary: type: - string - 'null' description: Border secondary color button_primary: type: - string - 'null' description: Primary button background color button_primary_hover: type: - string - 'null' description: Primary button hover color button_secondary: type: - string - 'null' description: Secondary button background color button_secondary_hover: type: - string - 'null' description: Secondary button hover color button_text_primary: type: - string - 'null' description: Primary button text color button_text_secondary: type: - string - 'null' description: Secondary button text color input_focus_border: type: - string - 'null' description: Input focus border color text_error: type: - string - 'null' description: Text error color text_placeholder: type: - string - 'null' description: Text placeholder color text_primary: type: - string - 'null' description: Text primary color text_secondary: type: - string - 'null' description: Text secondary color text_success: type: - string - 'null' description: Text success color FontSize: type: string description: Font size options for checkout UI enum: - xs - sm - md - lg - xl - 2xl FontWeight: type: string description: Font weight options for checkout UI enum: - normal - medium - bold - extraBold securitySchemes: API_KEY: type: http scheme: bearer ````