v6

latestOpenAPI 3.1.02026-07-311856741.1 MB

checkouts

public

Create Checkout Session

Create a checkout session.

Scopes: checkouts:write

post/v1/checkouts/

Request body

trial_interval'day' | 'week' | 'month' | 'year'

trial_interval_countinteger nullable

The number of interval units for the trial period.

metadataobject

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_dataobject

Key-value object storing custom field values.

discount_idstring uuid4 nullable

ID of the discount to apply to the checkout.

allow_discount_codesboolean

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_addressboolean

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.

amountinteger nullable

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

seatsinteger nullable

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

min_seatsinteger nullable

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

max_seatsinteger nullable

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

allow_trialboolean

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_idstring uuid4 nullable

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_customerboolean

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_idstring nullable

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_namestring nullable

The name of the customer.

customer_emailstring email nullable

Email address of the customer.

customer_ip_addressstring ipvanyaddress nullable

customer_billing_namestring nullable

customer_tax_idstring nullable

customer_metadataobject

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_idstring uuid4 nullable

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_urlstring uri nullable

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.

return_urlstring uri nullable

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

embed_originstring nullable

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.

localestring nullable

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.

currency'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'

productsstring[] required

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

pricesobject nullable

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.

Example request

{
  "customer_name": "John Doe",
  "customer_billing_address": {
    "country": "US"
  },
  "locale": "en"
}

Response

Checkout session created.

idstring uuid4 required

The ID of the object.

created_atstring date-time required

Creation timestamp of the object.

modified_atstring date-time nullable required

Last modification timestamp of the object.

custom_field_dataobject

Key-value object storing custom field values.

payment_processor'stripe' required

status'open' | 'expired' | 'confirmed' | 'succeeded' | 'failed' required

client_secretstring required

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

urlstring required

URL where the customer can access the checkout session.

expires_atstring date-time required

Expiration date and time of the checkout session.

success_urlstring required

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

return_urlstring nullable required

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

embed_originstring nullable 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.

amountinteger required

Amount in cents, before discounts and taxes.

seatsinteger nullable

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

min_seatsinteger nullable

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

max_seatsinteger nullable

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

discount_amountinteger required

Discount amount in cents.

net_amountinteger required

Amount in cents, after discounts but before taxes.

tax_amountinteger nullable required

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

tax_behavior'inclusive' | 'exclusive' required

total_amountinteger required

Amount in cents, after discounts and taxes.

currencystring required

Currency code of the checkout session.

allow_trialboolean nullable 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'day' | 'week' | 'month' | 'year' required

active_trial_interval_countinteger nullable 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_endstring date-time nullable required

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

organization_idstring uuid4 required

ID of the organization owning the checkout session.

product_idstring uuid4 nullable required

ID of the product to checkout.

product_price_idstring uuid4 nullable required

ID of the product price to checkout.

discount_idstring uuid4 nullable required

ID of the discount applied to the checkout.

allow_discount_codesboolean 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_addressboolean required

is_discount_applicableboolean required

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

is_free_product_priceboolean required

Whether the product price is free, regardless of discounts.

is_payment_requiredboolean required

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

is_payment_setup_requiredboolean 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_requiredboolean required

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

customer_idstring uuid4 nullable required

is_business_customerboolean 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_namestring nullable required

Name of the customer.

customer_emailstring nullable required

Email address of the customer.

customer_ip_addressstring ipvanyaddress nullable required

customer_billing_namestring nullable required

customer_tax_idstring nullable required

localestring nullable

payment_method_typestring nullable required

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

payment_processor_metadataobject required

trial_interval'day' | 'week' | 'month' | 'year' required

trial_interval_countinteger nullable required

The number of interval units for the trial period.

metadataMetadataOutputType required

external_customer_idstring nullable 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.

pricesobject nullable required

Mapping of product IDs to their list of prices.

subscription_idstring uuid4 nullable required

customer_metadataobject required