Skip to main content

​
Overview

Checkouts represent payment sessions where customers complete purchases. They handle payment collection, tax calculation, and order creation.

​
The Checkout Object

​
id
string
required
Unique identifier for the checkout session
​
client_secret
string
required
Secret used to access the checkout from client-side
​
status
enum
required
Status: open, confirmed, expired, or failed
​
url
string
required
URL to redirect customer to complete checkout
​
customer_id
string
ID of the customer (if known)
​
customer_email
string
Email address of the customer
​
product_id
string
required
ID of the product being purchased
​
product_price_id
string
required
ID of the selected price
​
amount
integer
Total amount in cents (null for custom pricing until confirmed)
​
tax_amount
integer
Tax amount in cents
​
currency
string
required
Three-letter ISO currency code
​
discount_id
string
Applied discount ID
​
subscription_id
string
Created subscription ID (after confirmation)
​
order_id
string
Created order ID (after confirmation)
​
created_at
string
required
Timestamp when checkout was created
​
expires_at
string
required
Timestamp when checkout expires

​
List Checkouts

cURL
curl -X GET "https://api.polar.sh/v1/checkouts" \
  -H "Authorization: Bearer polar_pat_..."

​
Query Parameters

​
page
integer
default:"1"
Page number
​
limit
integer
default:"20"
Items per page
​
organization_id
string
Filter by organization ID
​
product_id
string
Filter by product ID
​
customer_id
string
Filter by customer ID
​
external_customer_id
string
Filter by external customer ID
​
status
enum
Filter by status: open, confirmed, expired, failed
​
query
string
Filter by customer email

​
Get Checkout

cURL
curl -X GET "https://api.polar.sh/v1/checkouts/{id}" \
  -H "Authorization: Bearer polar_pat_..."

​
Path Parameters

​
id
string
required
Checkout session ID

​
Create Checkout

cURL
curl -X POST "https://api.polar.sh/v1/checkouts" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_123",
    "product_price_id": "price_456",
    "customer_email": "[email protected]",
    "success_url": "https://example.com/success"
  }'

​
Request Body

​
product_id
string
required
ID of the product to purchase
​
product_price_id
string
required
ID of the price to use
​
customer_email
string
Customer’s email address
​
customer_id
string
Existing customer ID
​
discount_id
string
Discount code to apply
​
amount
integer
Custom amount (for custom/PWYW pricing) in cents
​
success_url
string
URL to redirect after successful payment
​
metadata
object
Custom metadata

​
Response

​
201
Created
Returns the created checkout object with url to redirect customer

​
Update Checkout

cURL
curl -X PATCH "https://api.polar.sh/v1/checkouts/{id}" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "[email protected]"
  }'

​
Path Parameters

​
id
string
required
Checkout session ID

​
Request Body

​
customer_email
string
Update customer email
​
customer_billing_address
object
Update billing address
​
amount
integer
Update amount (for custom pricing)

​
Client Endpoints

These endpoints use the client secret instead of API authentication.

​
Get Checkout from Client

cURL
curl -X GET "https://api.polar.sh/v1/checkouts/client/{client_secret}"

​
Update from Client

cURL
curl -X PATCH "https://api.polar.sh/v1/checkouts/client/{client_secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "[email protected]"
  }'

​
Confirm Checkout

cURL
curl -X POST "https://api.polar.sh/v1/checkouts/client/{client_secret}/confirm" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmation_token_id": "tok_123"
  }'
​
confirmation_token_id
string
required
Payment token from Stripe or payment provider

​
Response

Returns the confirmed checkout with subscription_id and/or order_id.

​
Examples

​
Create Checkout for Subscription

curl -X POST "https://api.polar.sh/v1/checkouts" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_monthly_sub",
    "product_price_id": "price_2999",
    "customer_email": "[email protected]",
    "success_url": "https://myapp.com/success",
    "metadata": {
      "user_id": "12345"
    }
  }'

​
Apply Discount Code

curl -X POST "https://api.polar.sh/v1/checkouts" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_123",
    "product_price_id": "price_456",
    "customer_email": "[email protected]",
    "discount_id": "discount_SAVE20"
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us