POST
/
v1
/
checkouts
import { Polar } from "@polar-sh/sdk";

const polar = new Polar({
  accessToken: process.env["POLAR_ACCESS_TOKEN"] ?? "",
});

async function run() {
  const result = await polar.checkouts.create({
    allowDiscountCodes: true,
    customerBillingAddress: {
      country: "SE",
    },
    productId: "<value>",
  });

  // Handle the result
  console.log(result);
}

run();
{
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "custom_field_data": {},
  "payment_processor": "stripe",
  "status": "open",
  "client_secret": "<string>",
  "url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "success_url": "<string>",
  "embed_origin": "<string>",
  "amount": 50000024,
  "tax_amount": 123,
  "currency": "<string>",
  "subtotal_amount": 123,
  "total_amount": 123,
  "product_id": "<string>",
  "product_price_id": "<string>",
  "discount_id": "<string>",
  "allow_discount_codes": true,
  "is_discount_applicable": true,
  "is_free_product_price": true,
  "is_payment_required": true,
  "is_payment_setup_required": true,
  "is_payment_form_required": true,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "customer_email": "<string>",
  "customer_ip_address": "<string>",
  "customer_billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "US"
  },
  "customer_tax_id": "<string>",
  "payment_processor_metadata": {},
  "metadata": {},
  "customer_external_id": "<string>",
  "products": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "recurring_interval": "month",
      "is_recurring": true,
      "is_archived": true,
      "organization_id": "<string>",
      "prices": [
        {
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "id": "<string>",
          "amount_type": "<string>",
          "is_archived": true,
          "product_id": "<string>",
          "type": "<string>",
          "recurring_interval": "month",
          "price_currency": "<string>",
          "price_amount": 123,
          "legacy": true
        }
      ],
      "benefits": [
        {
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "id": "<string>",
          "type": "custom",
          "description": "<string>",
          "selectable": true,
          "deletable": true,
          "organization_id": "<string>"
        }
      ],
      "medias": [
        {
          "id": "<string>",
          "organization_id": "<string>",
          "name": "<string>",
          "path": "<string>",
          "mime_type": "<string>",
          "size": 123,
          "storage_version": "<string>",
          "checksum_etag": "<string>",
          "checksum_sha256_base64": "<string>",
          "checksum_sha256_hex": "<string>",
          "last_modified_at": "2023-11-07T05:31:56Z",
          "version": "<string>",
          "service": "<string>",
          "is_uploaded": true,
          "created_at": "2023-11-07T05:31:56Z",
          "size_readable": "<string>",
          "public_url": "<string>"
        }
      ]
    }
  ],
  "product": {
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "recurring_interval": "month",
    "is_recurring": true,
    "is_archived": true,
    "organization_id": "<string>",
    "prices": [
      {
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "amount_type": "<string>",
        "is_archived": true,
        "product_id": "<string>",
        "type": "<string>",
        "recurring_interval": "month",
        "price_currency": "<string>",
        "price_amount": 123,
        "legacy": true
      }
    ],
    "benefits": [
      {
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "type": "custom",
        "description": "<string>",
        "selectable": true,
        "deletable": true,
        "organization_id": "<string>"
      }
    ],
    "medias": [
      {
        "id": "<string>",
        "organization_id": "<string>",
        "name": "<string>",
        "path": "<string>",
        "mime_type": "<string>",
        "size": 123,
        "storage_version": "<string>",
        "checksum_etag": "<string>",
        "checksum_sha256_base64": "<string>",
        "checksum_sha256_hex": "<string>",
        "last_modified_at": "2023-11-07T05:31:56Z",
        "version": "<string>",
        "service": "<string>",
        "is_uploaded": true,
        "created_at": "2023-11-07T05:31:56Z",
        "size_readable": "<string>",
        "public_url": "<string>"
      }
    ]
  },
  "product_price": {
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "amount_type": "<string>",
    "is_archived": true,
    "product_id": "<string>",
    "type": "<string>",
    "recurring_interval": "month",
    "price_currency": "<string>",
    "price_amount": 123,
    "legacy": true
  },
  "discount": {
    "duration": "once",
    "type": "fixed",
    "amount": 123,
    "currency": "<string>",
    "id": "<string>",
    "name": "<string>",
    "code": "<string>"
  },
  "subscription_id": "<string>",
  "attached_custom_fields": [
    {
      "custom_field_id": "<string>",
      "custom_field": {
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "metadata": {},
        "type": "<string>",
        "slug": "<string>",
        "name": "<string>",
        "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
        "properties": {
          "form_label": "<string>",
          "form_help_text": "<string>",
          "form_placeholder": "<string>",
          "textarea": true,
          "min_length": 1,
          "max_length": 1
        }
      },
      "order": 123,
      "required": true
    }
  ],
  "customer_metadata": {}
}

Authorizations

​
Authorization
string
header
required

You can generate an Organization Access Token from your organization's settings.

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[]
required

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

​
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 boolean

You can store up to 50 key-value pairs.

​
custom_field_data
object

Key-value object storing custom field values.

​
discount_id
string | 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.

​
amount
integer | null

Amount to pay in cents. Only useful for custom prices, it'll be ignored for fixed and free prices.

Required range: 50 <= x <= 99999999
​
customer_id
string | 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.

​
customer_external_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

Name of the customer.

​
customer_email
string | null

Email address of the customer.

​
customer_ip_address
string | null
​
customer_billing_address
object | null

Billing address of the customer.

​
customer_tax_id
string | null
​
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 boolean

You can store up to 50 key-value pairs.

​
subscription_id
string | 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 | 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
​
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.

Response

201
application/json
Checkout session created.

Checkout session data retrieved using an access token.

​
created_at
string
required

Creation timestamp of the object.

​
modified_at
string | null
required

Last modification timestamp of the object.

​
id
string
required

The ID of the object.

​
payment_processor
enum<string>
required

Payment processor used.

Available options:
stripe
​
status
enum<string>
required

Status of the checkout session.

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
required

Expiration date and time of the checkout session.

​
success_url
string
required

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

​
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 | null
required

Amount to pay in cents. Only useful for custom prices, it'll be ignored for fixed and free prices.

Required range: 50 <= x <= 99999999
​
tax_amount
integer | null
required

Computed tax amount to pay in cents.

​
currency
string | null
required

Currency code of the checkout session.

​
subtotal_amount
integer | null
required

Subtotal amount in cents, including discounts and before tax.

​
total_amount
integer | null
required

Total amount to pay in cents, including discounts and after tax.

​
product_id
string
required

ID of the product to checkout.

​
product_price_id
string
required

ID of the product price to checkout.

​
discount_id
string | 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.

​
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 | null
required
​
customer_name
string | null
required

Name of the customer.

​
customer_email
string | null
required

Email address of the customer.

​
customer_ip_address
string | null
required
​
customer_billing_address
object | null
required

Billing address of the customer.

​
customer_tax_id
string | null
required
​
payment_processor_metadata
object
required
​
metadata
object
required
​
customer_external_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
object[]
required

List of products available to select.

Product data for a checkout session.

​
product
object
required

Product selected to checkout.

​
product_price
object
required

Price of the selected product.

​
discount
object | null
required

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

​
subscription_id
string | null
required
​
attached_custom_fields
object[]
required

Schema of a custom field attached to a resource.

​
customer_metadata
object
required
​
custom_field_data
object

Key-value object storing custom field values.

Was this page helpful?

Get Checkout Session
Next