// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
import { APIResource } from '../core/resource';
import * as MiscAPI from './misc';
import * as PaymentsAPI from './payments';
import * as SubscriptionsAPI from './subscriptions';
import { APIPromise } from '../core/api-promise';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';
export class CheckoutSessions extends APIResource {
create(body: CheckoutSessionCreateParams, options?: RequestOptions): APIPromise<CheckoutSessionResponse> {
return this._client.post('/checkouts', { body, ...options });
}
retrieve(id: string, options?: RequestOptions): APIPromise<CheckoutSessionStatus> {
return this._client.get(path`/checkouts/${id}`, options);
}
preview(
body: CheckoutSessionPreviewParams,
options?: RequestOptions,
): APIPromise<CheckoutSessionPreviewResponse> {
return this._client.post('/checkouts/preview', { body, ...options });
}
}
export interface CheckoutSessionBillingAddress {
/**
* Two-letter ISO country code (ISO 3166-1 alpha-2)
*/
country: MiscAPI.CountryCode;
/**
* City name
*/
city?: string | null;
/**
* State or province name
*/
state?: string | null;
/**
* Street address including house number and unit/apartment if applicable
*/
street?: string | null;
/**
* Postal code or ZIP code
*/
zipcode?: string | null;
}
export interface CheckoutSessionCustomization {
/**
* Force the checkout interface to render in a specific language (e.g. `en`, `es`)
*/
force_language?: string | null;
/**
* Show on demand tag
*
* Default is true
*/
show_on_demand_tag?: boolean;
/**
* Show order details by default
*
* Default is true
*/
show_order_details?: boolean;
/**
* Theme of the page (determines which mode - light/dark/system - to use)
*
* Default is `System`.
*/
theme?: 'dark' | 'light' | 'system';
/**
* Optional custom theme configuration with colors for light and dark modes
*/
theme_config?: ThemeConfig | null;
}
export interface CheckoutSessionFlags {
/**
* if customer is allowed to change currency, set it to true
*
* Default is true
*/
allow_currency_selection?: boolean;
allow_customer_editing_city?: boolean;
allow_customer_editing_country?: boolean;
allow_customer_editing_email?: boolean;
allow_customer_editing_name?: boolean;
allow_customer_editing_state?: boolean;
allow_customer_editing_street?: boolean;
allow_customer_editing_tax_id?: boolean;
allow_customer_editing_zipcode?: boolean;
/**
* If the customer is allowed to apply discount code, set it to true.
*
* Default is true
*/
allow_discount_code?: boolean;
/**
* If phone number is collected from customer, set it to rue
*
* Default is true
*/
allow_phone_number_collection?: boolean;
/**
* If the customer is allowed to add tax id, set it to true
*
* Default is true
*/
allow_tax_id?: boolean;
/**
* 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
*/
always_create_new_customer?: boolean;
/**
* If true, redirects the customer immediately after payment completion
*
* Default is false
*/
redirect_immediately?: boolean;
}
export interface CheckoutSessionRequest {
product_cart: Array<ProductItemReq>;
/**
* 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.
*/
allowed_payment_method_types?: Array<PaymentsAPI.PaymentMethodTypes> | null;
/**
* Billing address information for the session
*/
billing_address?: CheckoutSessionBillingAddress | null;
/**
* This field is ingored if adaptive pricing is disabled
*/
billing_currency?: MiscAPI.Currency | null;
/**
* If confirm is true, all the details will be finalized. If required data is
* missing, an API error is thrown.
*/
confirm?: boolean;
/**
* Custom fields to collect from customer during checkout (max 5 fields)
*/
custom_fields?: Array<CustomField> | null;
/**
* Customer details for the session
*/
customer?: PaymentsAPI.CustomerRequest | null;
/**
* Customization for the checkout session page
*/
customization?: CheckoutSessionCustomization;
discount_code?: string | null;
feature_flags?: CheckoutSessionFlags;
/**
* Override merchant default 3DS behaviour for this session
*/
force_3ds?: boolean | null;
/**
* Additional metadata associated with the payment. Defaults to empty if not
* provided.
*/
metadata?: { [key: string]: string } | null;
/**
* If true, only zipcode is required when confirm is true; other address fields
* remain optional
*/
minimal_address?: boolean;
/**
* 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.
*/
payment_method_id?: string | null;
/**
* Product collection ID for collection-based checkout flow
*/
product_collection_id?: string | null;
/**
* The url to redirect after payment failure or success.
*/
return_url?: string | null;
/**
* If true, returns a shortened checkout URL. Defaults to false if not specified.
*/
short_link?: boolean;
/**
* Display saved payment methods of a returning customer False by default
*/
show_saved_payment_methods?: boolean;
subscription_data?: SubscriptionData | null;
/**
* Tax ID for the customer (e.g. VAT number). Requires billing_address with
* country.
*/
tax_id?: string | null;
}
export interface CheckoutSessionResponse {
/**
* The ID of the created checkout session
*/
session_id: string;
/**
* Checkout url (None when payment_method_id is provided)
*/
checkout_url?: string | null;
}
export interface CheckoutSessionStatus {
/**
* Id of the checkout session
*/
id: string;
/**
* Created at timestamp
*/
created_at: string;
/**
* Customer email: prefers payment's customer, falls back to session
*/
customer_email?: string | null;
/**
* Customer name: prefers payment's customer, falls back to session
*/
customer_name?: string | null;
/**
* Id of the payment created by the checkout sessions.
*
* Null if checkout sessions is still at the details collection stage.
*/
payment_id?: string | null;
/**
* status of the payment.
*
* Null if checkout sessions is still at the details collection stage.
*/
payment_status?: PaymentsAPI.IntentStatus | null;
}
/**
* Definition of a custom field for checkout
*/
export interface CustomField {
/**
* Type of field determining validation rules
*/
field_type: 'text' | 'number' | 'email' | 'url' | 'date' | 'dropdown' | 'boolean';
/**
* Unique identifier for this field (used as key in responses)
*/
key: string;
/**
* Display label shown to customer
*/
label: string;
/**
* Options for dropdown type (required for dropdown, ignored for others)
*/
options?: Array<string> | null;
/**
* Placeholder text for the input
*/
placeholder?: string | null;
/**
* Whether this field is required
*/
required?: boolean;
}
export interface ProductItemReq {
/**
* unique id of the product
*/
product_id: string;
quantity: number;
/**
* only valid if product is a subscription
*/
addons?: Array<SubscriptionsAPI.AttachAddon> | null;
/**
* 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.
*/
amount?: number | null;
}
export interface SubscriptionData {
on_demand?: SubscriptionsAPI.OnDemandSubscription | null;
/**
* 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
*/
trial_period_days?: number | null;
}
/**
* Custom theme configuration with colors for light and dark modes.
*/
export interface ThemeConfig {
/**
* Dark mode color configuration
*/
dark?: ThemeModeConfig | null;
/**
* URL for the primary font. Must be a valid https:// URL.
*/
font_primary_url?: string | null;
/**
* URL for the secondary font. Must be a valid https:// URL.
*/
font_secondary_url?: string | null;
/**
* Font size for the checkout UI
*/
font_size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | null;
/**
* Font weight for the checkout UI
*/
font_weight?: 'normal' | 'medium' | 'bold' | 'extraBold' | null;
/**
* Light mode color configuration
*/
light?: ThemeModeConfig | null;
/**
* Custom text for the pay button (e.g., "Complete Purchase", "Subscribe Now"). Max
* 100 characters.
*/
pay_button_text?: string | null;
/**
* Border radius for UI elements. Must be a number followed by px, rem, or em
* (e.g., "4px", "0.5rem", "1em")
*/
radius?: string | null;
}
/**
* 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()`
*/
export interface ThemeModeConfig {
/**
* Background primary color
*
* Examples: `"#ffffff"`, `"rgb(255, 255, 255)"`, `"white"`
*/
bg_primary?: string | null;
/**
* Background secondary color
*/
bg_secondary?: string | null;
/**
* Border primary color
*/
border_primary?: string | null;
/**
* Border secondary color
*/
border_secondary?: string | null;
/**
* Primary button background color
*/
button_primary?: string | null;
/**
* Primary button hover color
*/
button_primary_hover?: string | null;
/**
* Secondary button background color
*/
button_secondary?: string | null;
/**
* Secondary button hover color
*/
button_secondary_hover?: string | null;
/**
* Primary button text color
*/
button_text_primary?: string | null;
/**
* Secondary button text color
*/
button_text_secondary?: string | null;
/**
* Input focus border color
*/
input_focus_border?: string | null;
/**
* Text error color
*/
text_error?: string | null;
/**
* Text placeholder color
*/
text_placeholder?: string | null;
/**
* Text primary color
*/
text_primary?: string | null;
/**
* Text secondary color
*/
text_secondary?: string | null;
/**
* Text success color
*/
text_success?: string | null;
}
/**
* Data returned by the calculate checkout session API
*/
export interface CheckoutSessionPreviewResponse {
/**
* Billing country
*/
billing_country: MiscAPI.CountryCode;
/**
* Currency in which the calculations were made
*/
currency: MiscAPI.Currency;
/**
* Breakup of the current payment
*/
current_breakup: CheckoutSessionPreviewResponse.CurrentBreakup;
/**
* The total product cart
*/
product_cart: Array<CheckoutSessionPreviewResponse.ProductCart>;
/**
* Total calculate price of the product cart
*/
total_price: number;
/**
* Breakup of recurring payments (None for one-time only)
*/
recurring_breakup?: CheckoutSessionPreviewResponse.RecurringBreakup | null;
/**
* Error message if tax ID validation failed
*/
tax_id_err_msg?: string | null;
/**
* Total tax
*/
total_tax?: number | null;
}
export namespace CheckoutSessionPreviewResponse {
/**
* Breakup of the current payment
*/
export interface CurrentBreakup {
/**
* Total discount amount
*/
discount: number;
/**
* Subtotal before discount (pre-tax original prices)
*/
subtotal: number;
/**
* Total amount to be charged (final amount after all calculations)
*/
total_amount: number;
/**
* Total tax amount
*/
tax?: number | null;
}
export interface ProductCart {
/**
* Credit entitlements that will be granted upon purchase
*/
credit_entitlements: Array<ProductCart.CreditEntitlement>;
/**
* the currency in which the calculatiosn were made
*/
currency: MiscAPI.Currency;
/**
* discounted price
*/
discounted_price: number;
/**
* Whether this is a subscription product (affects tax calculation in breakup)
*/
is_subscription: boolean;
is_usage_based: boolean;
meters: Array<ProductCart.Meter>;
/**
* the product currency
*/
og_currency: MiscAPI.Currency;
/**
* original price of the product
*/
og_price: number;
/**
* unique id of the product
*/
product_id: string;
/**
* Quanitity
*/
quantity: number;
/**
* tax category
*/
tax_category: MiscAPI.TaxCategory;
/**
* Whether tax is included in the price
*/
tax_inclusive: boolean;
/**
* tax rate
*/
tax_rate: number;
addons?: Array<ProductCart.Addon> | null;
description?: string | null;
/**
* discount percentage
*/
discount_amount?: number | null;
/**
* number of cycles the discount will apply
*/
discount_cycle?: number | null;
/**
* name of the product
*/
name?: string | null;
/**
* total tax
*/
tax?: number | null;
}
export namespace ProductCart {
/**
* Minimal credit entitlement info shown at checkout — what credits the customer
* will receive
*/
export interface CreditEntitlement {
/**
* ID of the credit entitlement
*/
credit_entitlement_id: string;
/**
* Name of the credit entitlement
*/
credit_entitlement_name: string;
/**
* Unit label (e.g. "API Calls", "Tokens")
*/
credit_entitlement_unit: string;
/**
* Number of credits granted
*/
credits_amount: string;
}
export interface Meter {
measurement_unit: string;
name: string;
price_per_unit: string;
description?: string | null;
free_threshold?: number | null;
}
export interface Addon {
addon_id: string;
currency: MiscAPI.Currency;
discounted_price: number;
name: string;
og_currency: MiscAPI.Currency;
og_price: number;
quantity: number;
/**
* Represents the different categories of taxation applicable to various products
* and services.
*/
tax_category: MiscAPI.TaxCategory;
tax_inclusive: boolean;
tax_rate: number;
description?: string | null;
discount_amount?: number | null;
tax?: number | null;
}
}
/**
* Breakup of recurring payments (None for one-time only)
*/
export interface RecurringBreakup {
/**
* Total discount amount
*/
discount: number;
/**
* Subtotal before discount (pre-tax original prices)
*/
subtotal: number;
/**
* Total recurring amount including tax
*/
total_amount: number;
/**
* Total tax on recurring payments
*/
tax?: number | null;
}
}
export interface CheckoutSessionCreateParams {
product_cart: Array<ProductItemReq>;
/**
* 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.
*/
allowed_payment_method_types?: Array<PaymentsAPI.PaymentMethodTypes> | null;
/**
* Billing address information for the session
*/
billing_address?: CheckoutSessionBillingAddress | null;
/**
* This field is ingored if adaptive pricing is disabled
*/
billing_currency?: MiscAPI.Currency | null;
/**
* If confirm is true, all the details will be finalized. If required data is
* missing, an API error is thrown.
*/
confirm?: boolean;
/**
* Custom fields to collect from customer during checkout (max 5 fields)
*/
custom_fields?: Array<CustomField> | null;
/**
* Customer details for the session
*/
customer?: PaymentsAPI.CustomerRequest | null;
/**
* Customization for the checkout session page
*/
customization?: CheckoutSessionCustomization;
discount_code?: string | null;
feature_flags?: CheckoutSessionFlags;
/**
* Override merchant default 3DS behaviour for this session
*/
force_3ds?: boolean | null;
/**
* Additional metadata associated with the payment. Defaults to empty if not
* provided.
*/
metadata?: { [key: string]: string } | null;
/**
* If true, only zipcode is required when confirm is true; other address fields
* remain optional
*/
minimal_address?: boolean;
/**
* 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.
*/
payment_method_id?: string | null;
/**
* Product collection ID for collection-based checkout flow
*/
product_collection_id?: string | null;
/**
* The url to redirect after payment failure or success.
*/
return_url?: string | null;
/**
* If true, returns a shortened checkout URL. Defaults to false if not specified.
*/
short_link?: boolean;
/**
* Display saved payment methods of a returning customer False by default
*/
show_saved_payment_methods?: boolean;
subscription_data?: SubscriptionData | null;
/**
* Tax ID for the customer (e.g. VAT number). Requires billing_address with
* country.
*/
tax_id?: string | null;
}
export interface CheckoutSessionPreviewParams {
product_cart: Array<ProductItemReq>;
/**
* 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.
*/
allowed_payment_method_types?: Array<PaymentsAPI.PaymentMethodTypes> | null;
/**
* Billing address information for the session
*/
billing_address?: CheckoutSessionBillingAddress | null;
/**
* This field is ingored if adaptive pricing is disabled
*/
billing_currency?: MiscAPI.Currency | null;
/**
* If confirm is true, all the details will be finalized. If required data is
* missing, an API error is thrown.
*/
confirm?: boolean;
/**
* Custom fields to collect from customer during checkout (max 5 fields)
*/
custom_fields?: Array<CustomField> | null;
/**
* Customer details for the session
*/
customer?: PaymentsAPI.CustomerRequest | null;
/**
* Customization for the checkout session page
*/
customization?: CheckoutSessionCustomization;
discount_code?: string | null;
feature_flags?: CheckoutSessionFlags;
/**
* Override merchant default 3DS behaviour for this session
*/
force_3ds?: boolean | null;
/**
* Additional metadata associated with the payment. Defaults to empty if not
* provided.
*/
metadata?: { [key: string]: string } | null;
/**
* If true, only zipcode is required when confirm is true; other address fields
* remain optional
*/
minimal_address?: boolean;
/**
* 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.
*/
payment_method_id?: string | null;
/**
* Product collection ID for collection-based checkout flow
*/
product_collection_id?: string | null;
/**
* The url to redirect after payment failure or success.
*/
return_url?: string | null;
/**
* If true, returns a shortened checkout URL. Defaults to false if not specified.
*/
short_link?: boolean;
/**
* Display saved payment methods of a returning customer False by default
*/
show_saved_payment_methods?: boolean;
subscription_data?: SubscriptionData | null;
/**
* Tax ID for the customer (e.g. VAT number). Requires billing_address with
* country.
*/
tax_id?: string | null;
}
export declare namespace CheckoutSessions {
export {
type CheckoutSessionBillingAddress as CheckoutSessionBillingAddress,
type CheckoutSessionCustomization as CheckoutSessionCustomization,
type CheckoutSessionFlags as CheckoutSessionFlags,
type CheckoutSessionRequest as CheckoutSessionRequest,
type CheckoutSessionResponse as CheckoutSessionResponse,
type CheckoutSessionStatus as CheckoutSessionStatus,
type CustomField as CustomField,
type ProductItemReq as ProductItemReq,
type SubscriptionData as SubscriptionData,
type ThemeConfig as ThemeConfig,
type ThemeModeConfig as ThemeModeConfig,
type CheckoutSessionPreviewResponse as CheckoutSessionPreviewResponse,
type CheckoutSessionCreateParams as CheckoutSessionCreateParams,
type CheckoutSessionPreviewParams as CheckoutSessionPreviewParams,
};
}
