Skip to main content
POST
Python

Authorizations

Authorization
string
header
required

You can generate a Personal Access Token from your settings.

Scopes

checkouts:write
pat
checkouts:write
oat

Body

application/json

Create a new checkout session from a list of products. Customers will be able to switch between those products.

Metadata set on the checkout will be copied to the resulting order and/or subscription.

products
string<uuid4>[]
required

List of product IDs available to select at that checkout. The first one will be selected by default.

Minimum array length: 1
trial_interval
enum<string> | null

The interval unit for the trial period.

Available options:
day,
week,
month,
year
trial_interval_count
integer | null

The number of interval units for the trial period.

Required range: 1 <= x <= 1000
metadata
Metadata · object

Key-value object allowing you to store additional information.

The key must be a string with a maximum length of 40 characters. The value must be either:

  • A string with a maximum length of 500 characters
  • An integer
  • A floating-point number
  • A boolean

You can store up to 50 key-value pairs.

custom_field_data
Custom Field Data · object

Key-value object storing custom field values.

discount_id
string<uuid4> | null

ID of the discount to apply to the checkout.

allow_discount_codes
boolean
default:true

Whether to allow the customer to apply discount codes. If you apply a discount through discount_id, it'll still be applied, but the customer won't be able to change it.

require_billing_address
boolean
default:false

Whether to require the customer to fill their full billing address, instead of just the country. Customers in the US will always be required to fill their full address, regardless of this setting. If you preset the billing address, this setting will be automatically set to true.

amount
integer | null

Amount in cents, before discounts and taxes. Only useful for custom prices, it'll be ignored for fixed and free prices.

Required range: x >= 0
seats
integer | null

Predefined number of seats (works with seat-based pricing only)

Required range: 1 <= x <= 10000
min_seats
integer | null

Minimum number of seats (works with seat-based pricing only)

Required range: 1 <= x <= 10000
max_seats
integer | null

Maximum number of seats (works with seat-based pricing only)

Required range: 1 <= x <= 10000
units
integer | null

Predefined number of units (works with unit-based pricing only)

Required range: 1 <= x <= 2147483647
min_units
integer | null

Minimum number of units (works with unit-based pricing only)

Required range: 1 <= x <= 2147483647
max_units
integer | null

Maximum number of units (works with unit-based pricing only)

Required range: 1 <= x <= 2147483647
allow_trial
boolean
default:true

Whether to enable the trial period for the checkout session. If false, the trial period will be disabled, even if the selected product has a trial configured.

customer_id
string<uuid4> | null

ID of an existing customer in the organization. The customer data will be pre-filled in the checkout form. The resulting order will be linked to this customer.

is_business_customer
boolean
default:false

Whether the customer is a business or an individual. If true, the customer will be required to fill their full billing address and billing name.

external_customer_id
string | null

ID of the customer in your system. If a matching customer exists on Polar, the resulting order will be linked to this customer. Otherwise, a new customer will be created with this external ID set.

customer_name
string | null

The name of the customer.

Maximum string length: 256
Example:

"John Doe"

customer_email
string<email> | null

Email address of the customer.

customer_ip_address
string<ipvanyaddress> | null
customer_billing_name
string | null
Maximum string length: 256
customer_billing_address
AddressInput · object | null

Billing address of the customer.

customer_tax_id
string | null
customer_metadata
Customer Metadata · object

Key-value object allowing you to store additional information that'll be copied to the created customer.

The key must be a string with a maximum length of 40 characters. The value must be either:

  • A string with a maximum length of 500 characters
  • An integer
  • A floating-point number
  • A boolean

You can store up to 50 key-value pairs.

subscription_id
string<uuid4> | null

ID of a subscription to upgrade. It must be on a free pricing. If checkout is successful, metadata set on this checkout will be copied to the subscription, and existing keys will be overwritten.

success_url
string<uri> | null

URL where the customer will be redirected after a successful payment.You can add the checkout_id={CHECKOUT_ID} query parameter to retrieve the checkout session id.

Required string length: 1 - 2083
return_url
string<uri> | null

When set, a back button will be shown in the checkout to return to this URL.

Required string length: 1 - 2083
embed_origin
string | null

If you plan to embed the checkout session, set this to the Origin of the embedding page. It'll allow the Polar iframe to communicate with the parent page.

locale
string | null

Locale of the customer, given as an IETF BCP 47 language tag, e.g. en, en-US or en-GB-oxendict. If null or unsupported, the locale will default to en.

Example:

"en"

currency
enum<string> | null
Available options:
aed,
all,
amd,
aoa,
ars,
aud,
awg,
azn,
bam,
bbd,
bdt,
bif,
bmd,
bnd,
bob,
brl,
bsd,
bwp,
bzd,
cad,
cdf,
chf,
clp,
cny,
cop,
crc,
cve,
czk,
djf,
dkk,
dop,
dzd,
egp,
etb,
eur,
fjd,
fkp,
gbp,
gel,
gip,
gmd,
gnf,
gtq,
gyd,
hkd,
hnl,
htg,
huf,
idr,
ils,
inr,
isk,
jmd,
jpy,
kes,
kgs,
khr,
kmf,
krw,
kyd,
kzt,
lak,
lkr,
lrd,
lsl,
mad,
mdl,
mga,
mkd,
mnt,
mop,
mur,
mvr,
mwk,
mxn,
myr,
mzn,
nad,
ngn,
nio,
nok,
npr,
nzd,
pab,
pen,
pgk,
php,
pkr,
pln,
pyg,
qar,
ron,
rsd,
rwf,
sar,
sbd,
scr,
sek,
sgd,
shp,
sos,
srd,
szl,
thb,
tjs,
top,
try,
ttd,
twd,
tzs,
uah,
ugx,
usd,
uyu,
uzs,
vnd,
vuv,
wst,
xaf,
xcd,
xcg,
xof,
xpf,
yer,
zar,
zmw
Required string length: 3
prices
Prices · object | null

Optional mapping of product IDs to a list of ad-hoc prices to create for that product. If not set, catalog prices of the product will be used.

Response

Checkout session created.

Checkout session data retrieved using an access token.

id
string<uuid4>
required

The ID of the object.

created_at
string<date-time>
required

Creation timestamp of the object.

Example:

"2026-01-01T00:00:00.000000Z"

modified_at
string<date-time> | null
required

Last modification timestamp of the object.

Example:

"2026-01-01T00:00:00.000000Z"

payment_processor
enum<string>
required

Payment processor used.

Available options:
stripe
status
enum<string>
required
Available options:
open,
expired,
confirmed,
succeeded,
failed
client_secret
string
required

Client secret used to update and complete the checkout session from the client.

url
string
required

URL where the customer can access the checkout session.

expires_at
string<date-time>
required

Expiration date and time of the checkout session.

Example:

"2026-01-01T00:00:00.000000Z"

success_url
string
required

URL where the customer will be redirected after a successful payment.

return_url
string | null
required

When set, a back button will be shown in the checkout to return to this URL.

embed_origin
string | null
required

When checkout is embedded, represents the Origin of the page embedding the checkout. Used as a security measure to send messages only to the embedding page.

amount
integer
required

Amount in cents, before discounts and taxes.

units
integer | null
required

Predefined number of units (works with unit-based pricing only)

min_units
integer | null
required

Minimum number of units (works with unit-based pricing only)

max_units
integer | null
required

Maximum number of units (works with unit-based pricing only)

discount_amount
integer
required

Discount amount in cents.

net_amount
integer
required

Amount in cents, after discounts but before taxes.

tax_amount
integer | null
required

Sales tax amount in cents. If null, it means there is no enough information yet to calculate it.

tax_behavior
enum<string> | null
required

Tax behavior of the checkout. inclusive means the price includes tax, exclusive means tax is added on top. If null, tax is not yet calculated.

Available options:
inclusive,
exclusive
total_amount
integer
required

Amount in cents, after discounts and taxes.

currency
string
required

Currency code of the checkout session.

allow_trial
boolean | null
required

Whether to enable the trial period for the checkout session. If false, the trial period will be disabled, even if the selected product has a trial configured.

active_trial_interval
enum<string> | null
required

Interval unit of the trial period, if any. This value is either set from the checkout, if trial_interval is set, or from the selected product.

Available options:
day,
week,
month,
year
active_trial_interval_count
integer | null
required

Number of interval units of the trial period, if any. This value is either set from the checkout, if trial_interval_count is set, or from the selected product.

trial_end
string<date-time> | null
required

End date and time of the trial period, if any.

Example:

"2026-01-01T00:00:00.000000Z"

organization_id
string<uuid4>
required

ID of the organization owning the checkout session.

product_id
string<uuid4> | null
required

ID of the product to checkout.

discount_id
string<uuid4> | null
required

ID of the discount applied to the checkout.

allow_discount_codes
boolean
required

Whether to allow the customer to apply discount codes. If you apply a discount through discount_id, it'll still be applied, but the customer won't be able to change it.

require_billing_address
boolean
required

Whether to require the customer to fill their full billing address, instead of just the country. Customers in the US will always be required to fill their full address, regardless of this setting. If you preset the billing address, this setting will be automatically set to true.

is_discount_applicable
boolean
required

Whether the discount is applicable to the checkout. Typically, free and custom prices are not discountable.

is_free_product_price
boolean
required

Whether the product price is free, regardless of discounts.

is_payment_required
boolean
required

Whether the checkout requires payment, e.g. in case of free products or discounts that cover the total amount.

is_payment_setup_required
boolean
required

Whether the checkout requires setting up a payment method, regardless of the amount, e.g. subscriptions that have first free cycles.

is_payment_form_required
boolean
required

Whether the checkout requires a payment form, whether because of a payment or payment method setup.

customer_id
string<uuid4> | null
required
is_business_customer
boolean
required

Whether the customer is a business or an individual. If true, the customer will be required to fill their full billing address and billing name.

customer_name
string | null
required

Name of the customer.

customer_email
string | null
required

Email address of the customer.

customer_ip_address
string<ipvanyaddress> | null
required
customer_billing_name
string | null
required
customer_billing_address
Address · object | null
required

Billing address of the customer.

customer_tax_id
string | null
required
payment_method_type
string | null
required

Payment method type selected by the customer in the checkout form, e.g. card, apple_pay or upi.

payment_processor_metadata
Payment Processor Metadata · object
required
billing_address_fields
CheckoutBillingAddressFields · object
required

Determine which billing address fields should be disabled, optional or required in the checkout form.

trial_interval
enum<string> | null
required

The interval unit for the trial period.

Available options:
day,
week,
month,
year
trial_interval_count
integer | null
required

The number of interval units for the trial period.

metadata
object
required
external_customer_id
string | null
required

ID of the customer in your system. If a matching customer exists on Polar, the resulting order will be linked to this customer. Otherwise, a new customer will be created with this external ID set.

products
CheckoutProduct · object[]
required

List of products available to select.

product
CheckoutProduct · object | null
required

Product selected to checkout.

product_price
ProductPriceFixed · object
required
deprecated

A fixed price for a product.

prices
Prices · object | null
required

Mapping of product IDs to their list of prices.

discount
CheckoutDiscountFixedOnceForeverDuration · object
required

Schema for a fixed amount discount that is applied once or forever.

subscription_id
string<uuid4> | null
required
attached_custom_fields
AttachedCustomField · object[] | null
required
customer_metadata
Customer Metadata · object
required
custom_field_data
Custom Field Data · object

Key-value object storing custom field values.

seats
integer | null

Predefined number of seats (works with seat-based pricing only)

min_seats
integer | null

Minimum number of seats (works with seat-based pricing only)

max_seats
integer | null

Maximum number of seats (works with seat-based pricing only)

locale
string | null