Update Checkout Session

PATCH

checkouts

{id}

Python

from polar.v2027_01 import Polar

polar = Polar("polar_oat_xxx")

response = polar.checkouts.update(
    '00000000-0000-4000-8000-000000000000',
)
print(response)

import { createPolar } from "@polar-sh/sdk/2027-01";

const polar = createPolar({
  accessToken: "polar_oat_xxx",
});

const response = await polar.checkouts.update(
  "00000000-0000-4000-8000-000000000000",
  {},
);
console.log(response);

curl --request PATCH \
  --url https://api.polar.sh/v1/checkouts/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "custom_field_data": {},
  "product_id": "<string>",
  "amount": 1,
  "seats": 5000,
  "units": 1073741824,
  "is_business_customer": true,
  "customer_name": "John Doe",
  "customer_email": "[email protected]",
  "customer_billing_name": "<string>",
  "customer_billing_address": {
    "country": "US",
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "customer_tax_id": "<string>",
  "locale": "en",
  "trial_interval_count": 500,
  "metadata": {},
  "discount_id": "<string>",
  "allow_discount_codes": true,
  "require_billing_address": true,
  "allow_trial": true,
  "customer_ip_address": "<string>",
  "customer_metadata": {},
  "success_url": "<string>",
  "return_url": "<string>",
  "embed_origin": "<string>"
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    custom_field_data: {},
    product_id: '<string>',
    amount: 1,
    seats: 5000,
    units: 1073741824,
    is_business_customer: true,
    customer_name: 'John Doe',
    customer_email: '[email protected]',
    customer_billing_name: '<string>',
    customer_billing_address: {
      country: 'US',
      line1: '<string>',
      line2: '<string>',
      postal_code: '<string>',
      city: '<string>',
      state: '<string>'
    },
    customer_tax_id: '<string>',
    locale: 'en',
    trial_interval_count: 500,
    metadata: {},
    discount_id: '<string>',
    allow_discount_codes: true,
    require_billing_address: true,
    allow_trial: true,
    customer_ip_address: '<string>',
    customer_metadata: {},
    success_url: '<string>',
    return_url: '<string>',
    embed_origin: '<string>'
  })
};

fetch('https://api.polar.sh/v1/checkouts/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polar.sh/v1/checkouts/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'custom_field_data' => [
        
    ],
    'product_id' => '<string>',
    'amount' => 1,
    'seats' => 5000,
    'units' => 1073741824,
    'is_business_customer' => true,
    'customer_name' => 'John Doe',
    'customer_email' => '[email protected]',
    'customer_billing_name' => '<string>',
    'customer_billing_address' => [
        'country' => 'US',
        'line1' => '<string>',
        'line2' => '<string>',
        'postal_code' => '<string>',
        'city' => '<string>',
        'state' => '<string>'
    ],
    'customer_tax_id' => '<string>',
    'locale' => 'en',
    'trial_interval_count' => 500,
    'metadata' => [
        
    ],
    'discount_id' => '<string>',
    'allow_discount_codes' => true,
    'require_billing_address' => true,
    'allow_trial' => true,
    'customer_ip_address' => '<string>',
    'customer_metadata' => [
        
    ],
    'success_url' => '<string>',
    'return_url' => '<string>',
    'embed_origin' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polar.sh/v1/checkouts/{id}"

	payload := strings.NewReader("{\n  \"custom_field_data\": {},\n  \"product_id\": \"<string>\",\n  \"amount\": 1,\n  \"seats\": 5000,\n  \"units\": 1073741824,\n  \"is_business_customer\": true,\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"[email protected]\",\n  \"customer_billing_name\": \"<string>\",\n  \"customer_billing_address\": {\n    \"country\": \"US\",\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"customer_tax_id\": \"<string>\",\n  \"locale\": \"en\",\n  \"trial_interval_count\": 500,\n  \"metadata\": {},\n  \"discount_id\": \"<string>\",\n  \"allow_discount_codes\": true,\n  \"require_billing_address\": true,\n  \"allow_trial\": true,\n  \"customer_ip_address\": \"<string>\",\n  \"customer_metadata\": {},\n  \"success_url\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"embed_origin\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.polar.sh/v1/checkouts/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"custom_field_data\": {},\n  \"product_id\": \"<string>\",\n  \"amount\": 1,\n  \"seats\": 5000,\n  \"units\": 1073741824,\n  \"is_business_customer\": true,\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"[email protected]\",\n  \"customer_billing_name\": \"<string>\",\n  \"customer_billing_address\": {\n    \"country\": \"US\",\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"customer_tax_id\": \"<string>\",\n  \"locale\": \"en\",\n  \"trial_interval_count\": 500,\n  \"metadata\": {},\n  \"discount_id\": \"<string>\",\n  \"allow_discount_codes\": true,\n  \"require_billing_address\": true,\n  \"allow_trial\": true,\n  \"customer_ip_address\": \"<string>\",\n  \"customer_metadata\": {},\n  \"success_url\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"embed_origin\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.polar.sh/v1/checkouts/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"custom_field_data\": {},\n  \"product_id\": \"<string>\",\n  \"amount\": 1,\n  \"seats\": 5000,\n  \"units\": 1073741824,\n  \"is_business_customer\": true,\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"[email protected]\",\n  \"customer_billing_name\": \"<string>\",\n  \"customer_billing_address\": {\n    \"country\": \"US\",\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"customer_tax_id\": \"<string>\",\n  \"locale\": \"en\",\n  \"trial_interval_count\": 500,\n  \"metadata\": {},\n  \"discount_id\": \"<string>\",\n  \"allow_discount_codes\": true,\n  \"require_billing_address\": true,\n  \"allow_trial\": true,\n  \"customer_ip_address\": \"<string>\",\n  \"customer_metadata\": {},\n  \"success_url\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"embed_origin\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "payment_processor": "stripe",
  "status": "open",
  "client_secret": "<string>",
  "url": "<string>",
  "expires_at": "2026-01-01T00:00:00.000000Z",
  "success_url": "<string>",
  "return_url": "<string>",
  "embed_origin": "<string>",
  "amount": 123,
  "units": 123,
  "min_units": 123,
  "max_units": 123,
  "discount_amount": 123,
  "net_amount": 123,
  "tax_amount": 123,
  "tax_behavior": "inclusive",
  "total_amount": 123,
  "currency": "<string>",
  "allow_trial": true,
  "active_trial_interval": "day",
  "active_trial_interval_count": 123,
  "trial_end": "2026-01-01T00:00:00.000000Z",
  "organization_id": "<string>",
  "product_id": "<string>",
  "discount_id": "<string>",
  "allow_discount_codes": true,
  "require_billing_address": 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>",
  "is_business_customer": true,
  "customer_name": "<string>",
  "customer_email": "<string>",
  "customer_ip_address": "<string>",
  "customer_billing_name": "<string>",
  "customer_billing_address": {
    "country": "US",
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "customer_tax_id": "<string>",
  "payment_method_type": "<string>",
  "payment_processor_metadata": {},
  "billing_address_fields": {
    "country": "required",
    "state": "required",
    "city": "required",
    "postal_code": "required",
    "line1": "required",
    "line2": "required"
  },
  "trial_interval": "day",
  "trial_interval_count": 123,
  "metadata": {},
  "external_customer_id": "<string>",
  "products": [
    {
      "id": "<string>",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "trial_interval": "day",
      "trial_interval_count": 123,
      "name": "<string>",
      "description": "<string>",
      "visibility": "draft",
      "recurring_interval": "day",
      "recurring_interval_count": 123,
      "meter_interval": "day",
      "meter_interval_count": 123,
      "is_recurring": true,
      "is_archived": true,
      "organization_id": "<string>",
      "catalog_id": "<string>",
      "is_current": true,
      "prices": [
        {
          "created_at": "2026-01-01T00:00:00.000000Z",
          "modified_at": "2026-01-01T00:00:00.000000Z",
          "id": "<string>",
          "source": "catalog",
          "amount_type": "fixed",
          "price_currency": "<string>",
          "tax_behavior": "location",
          "is_archived": true,
          "product_id": "<string>",
          "price_amount": 123
        }
      ],
      "benefits": [
        {
          "id": "<string>",
          "created_at": "2026-01-01T00:00:00.000000Z",
          "modified_at": "2026-01-01T00:00:00.000000Z",
          "type": "custom",
          "description": "<string>",
          "selectable": true,
          "deletable": true,
          "is_deleted": 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": "2026-01-01T00:00:00.000000Z",
          "version": "<string>",
          "service": "product_media",
          "is_uploaded": true,
          "created_at": "2026-01-01T00:00:00.000000Z",
          "size_readable": "<string>",
          "public_url": "<string>"
        }
      ]
    }
  ],
  "product": {
    "id": "<string>",
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "trial_interval": "day",
    "trial_interval_count": 123,
    "name": "<string>",
    "description": "<string>",
    "visibility": "draft",
    "recurring_interval": "day",
    "recurring_interval_count": 123,
    "meter_interval": "day",
    "meter_interval_count": 123,
    "is_recurring": true,
    "is_archived": true,
    "organization_id": "<string>",
    "catalog_id": "<string>",
    "is_current": true,
    "prices": [
      {
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "id": "<string>",
        "source": "catalog",
        "amount_type": "fixed",
        "price_currency": "<string>",
        "tax_behavior": "location",
        "is_archived": true,
        "product_id": "<string>",
        "price_amount": 123
      }
    ],
    "benefits": [
      {
        "id": "<string>",
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "type": "custom",
        "description": "<string>",
        "selectable": true,
        "deletable": true,
        "is_deleted": 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": "2026-01-01T00:00:00.000000Z",
        "version": "<string>",
        "service": "product_media",
        "is_uploaded": true,
        "created_at": "2026-01-01T00:00:00.000000Z",
        "size_readable": "<string>",
        "public_url": "<string>"
      }
    ]
  },
  "product_price": {
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "id": "<string>",
    "source": "catalog",
    "amount_type": "fixed",
    "price_currency": "<string>",
    "tax_behavior": "location",
    "is_archived": true,
    "product_id": "<string>",
    "price_amount": 123
  },
  "prices": {},
  "discount": {
    "duration": "once",
    "type": "fixed",
    "amounts": {
      "eur": 900,
      "usd": 1000
    },
    "id": "<string>",
    "name": "<string>",
    "code": "<string>"
  },
  "subscription_id": "<string>",
  "attached_custom_fields": [
    {
      "custom_field_id": "<string>",
      "custom_field": {
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "id": "<string>",
        "metadata": {},
        "type": "text",
        "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": 1073741823,
          "max_length": 1073741823
        }
      },
      "order": 123,
      "required": true
    }
  ],
  "customer_metadata": {},
  "custom_field_data": {},
  "seats": 123,
  "min_seats": 123,
  "max_seats": 123,
  "locale": "<string>"
}

{
  "error": "AlreadyActiveSubscriptionError",
  "detail": "<string>"
}

{
  "error": "ResourceNotFound",
  "detail": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

You can generate a Personal Access Token from your settings.

Scopes

checkouts:write

pat

checkouts:write

oat

Path Parameters

string<uuid4>

required

The checkout session ID.

Body

application/json

Update an existing checkout session using an access token.

custom_field_data

Custom Field Data · object

Key-value object storing custom field values.

Show child attributes

product_id

string<uuid4> | null

ID of the product to checkout. Must be present in the checkout's product list.

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

Number of seats for seat-based pricing.

Required range: 1 <= x <= 10000

units

integer | null

Number of units for unit-based pricing.

Required range: 1 <= x <= 2147483647

is_business_customer

boolean | null

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_billing_name

string | null

Maximum string length: 256

customer_billing_address

AddressInput · object | null

Billing address of the customer.

Show child attributes

customer_tax_id

string | null

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"

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.

Show child attributes

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

discount_id

string<uuid4> | null

ID of the discount to apply to the checkout.

allow_discount_codes

boolean | null

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

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.

allow_trial

boolean | null

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_ip_address

string<ipvanyaddress> | null

customer_metadata

Customer Metadata · object | null

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.

Show child attributes

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.

Response

Checkout session updated.

Checkout session data retrieved using an access token.

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

Status of the checkout session.

    - Open: the checkout session was opened.
    - Expired: the checkout session was expired and is no more accessible.
    - Confirmed: the user on the checkout session clicked Pay. This is not indicative of the payment's success status.
    - Failed: the checkout definitely failed for technical reasons and cannot be retried. In most cases, this state is never reached.
    - Succeeded: the payment on the checkout was performed successfully.

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

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.

Show child attributes

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

Show child attributes

billing_address_fields

CheckoutBillingAddressFields · object

required

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

Show child attributes

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

Show child attributes

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.

Show child attributes

product

CheckoutProduct · object | null

required

Product selected to checkout.

Show child attributes

product_price

ProductPriceFixed · object

required

deprecated

A fixed price for a product.

Show child attributes

prices

Prices · object | null

required

Mapping of product IDs to their list of prices.

Show child attributes

discount

CheckoutDiscountFixedOnceForeverDuration · object

required

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

CheckoutDiscountFixedOnceForeverDuration
CheckoutDiscountFixedRepeatDuration
CheckoutDiscountPercentageOnceForeverDuration
CheckoutDiscountPercentageRepeatDuration

Show child attributes

subscription_id

string<uuid4> | null

required

attached_custom_fields

AttachedCustomField · object[] | null

required

Show child attributes

customer_metadata

Customer Metadata · object

required

Show child attributes

custom_field_data

Custom Field Data · object

Key-value object storing custom field values.

Show child attributes

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

⌘I

Python

from polar.v2027_01 import Polar

polar = Polar("polar_oat_xxx")

response = polar.checkouts.update(
    '00000000-0000-4000-8000-000000000000',
)
print(response)

import { createPolar } from "@polar-sh/sdk/2027-01";

const polar = createPolar({
  accessToken: "polar_oat_xxx",
});

const response = await polar.checkouts.update(
  "00000000-0000-4000-8000-000000000000",
  {},
);
console.log(response);

curl --request PATCH \
  --url https://api.polar.sh/v1/checkouts/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "custom_field_data": {},
  "product_id": "<string>",
  "amount": 1,
  "seats": 5000,
  "units": 1073741824,
  "is_business_customer": true,
  "customer_name": "John Doe",
  "customer_email": "[email protected]",
  "customer_billing_name": "<string>",
  "customer_billing_address": {
    "country": "US",
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "customer_tax_id": "<string>",
  "locale": "en",
  "trial_interval_count": 500,
  "metadata": {},
  "discount_id": "<string>",
  "allow_discount_codes": true,
  "require_billing_address": true,
  "allow_trial": true,
  "customer_ip_address": "<string>",
  "customer_metadata": {},
  "success_url": "<string>",
  "return_url": "<string>",
  "embed_origin": "<string>"
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    custom_field_data: {},
    product_id: '<string>',
    amount: 1,
    seats: 5000,
    units: 1073741824,
    is_business_customer: true,
    customer_name: 'John Doe',
    customer_email: '[email protected]',
    customer_billing_name: '<string>',
    customer_billing_address: {
      country: 'US',
      line1: '<string>',
      line2: '<string>',
      postal_code: '<string>',
      city: '<string>',
      state: '<string>'
    },
    customer_tax_id: '<string>',
    locale: 'en',
    trial_interval_count: 500,
    metadata: {},
    discount_id: '<string>',
    allow_discount_codes: true,
    require_billing_address: true,
    allow_trial: true,
    customer_ip_address: '<string>',
    customer_metadata: {},
    success_url: '<string>',
    return_url: '<string>',
    embed_origin: '<string>'
  })
};

fetch('https://api.polar.sh/v1/checkouts/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polar.sh/v1/checkouts/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'custom_field_data' => [
        
    ],
    'product_id' => '<string>',
    'amount' => 1,
    'seats' => 5000,
    'units' => 1073741824,
    'is_business_customer' => true,
    'customer_name' => 'John Doe',
    'customer_email' => '[email protected]',
    'customer_billing_name' => '<string>',
    'customer_billing_address' => [
        'country' => 'US',
        'line1' => '<string>',
        'line2' => '<string>',
        'postal_code' => '<string>',
        'city' => '<string>',
        'state' => '<string>'
    ],
    'customer_tax_id' => '<string>',
    'locale' => 'en',
    'trial_interval_count' => 500,
    'metadata' => [
        
    ],
    'discount_id' => '<string>',
    'allow_discount_codes' => true,
    'require_billing_address' => true,
    'allow_trial' => true,
    'customer_ip_address' => '<string>',
    'customer_metadata' => [
        
    ],
    'success_url' => '<string>',
    'return_url' => '<string>',
    'embed_origin' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polar.sh/v1/checkouts/{id}"

	payload := strings.NewReader("{\n  \"custom_field_data\": {},\n  \"product_id\": \"<string>\",\n  \"amount\": 1,\n  \"seats\": 5000,\n  \"units\": 1073741824,\n  \"is_business_customer\": true,\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"[email protected]\",\n  \"customer_billing_name\": \"<string>\",\n  \"customer_billing_address\": {\n    \"country\": \"US\",\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"customer_tax_id\": \"<string>\",\n  \"locale\": \"en\",\n  \"trial_interval_count\": 500,\n  \"metadata\": {},\n  \"discount_id\": \"<string>\",\n  \"allow_discount_codes\": true,\n  \"require_billing_address\": true,\n  \"allow_trial\": true,\n  \"customer_ip_address\": \"<string>\",\n  \"customer_metadata\": {},\n  \"success_url\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"embed_origin\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.polar.sh/v1/checkouts/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"custom_field_data\": {},\n  \"product_id\": \"<string>\",\n  \"amount\": 1,\n  \"seats\": 5000,\n  \"units\": 1073741824,\n  \"is_business_customer\": true,\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"[email protected]\",\n  \"customer_billing_name\": \"<string>\",\n  \"customer_billing_address\": {\n    \"country\": \"US\",\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"customer_tax_id\": \"<string>\",\n  \"locale\": \"en\",\n  \"trial_interval_count\": 500,\n  \"metadata\": {},\n  \"discount_id\": \"<string>\",\n  \"allow_discount_codes\": true,\n  \"require_billing_address\": true,\n  \"allow_trial\": true,\n  \"customer_ip_address\": \"<string>\",\n  \"customer_metadata\": {},\n  \"success_url\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"embed_origin\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.polar.sh/v1/checkouts/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"custom_field_data\": {},\n  \"product_id\": \"<string>\",\n  \"amount\": 1,\n  \"seats\": 5000,\n  \"units\": 1073741824,\n  \"is_business_customer\": true,\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"[email protected]\",\n  \"customer_billing_name\": \"<string>\",\n  \"customer_billing_address\": {\n    \"country\": \"US\",\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"customer_tax_id\": \"<string>\",\n  \"locale\": \"en\",\n  \"trial_interval_count\": 500,\n  \"metadata\": {},\n  \"discount_id\": \"<string>\",\n  \"allow_discount_codes\": true,\n  \"require_billing_address\": true,\n  \"allow_trial\": true,\n  \"customer_ip_address\": \"<string>\",\n  \"customer_metadata\": {},\n  \"success_url\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"embed_origin\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "payment_processor": "stripe",
  "status": "open",
  "client_secret": "<string>",
  "url": "<string>",
  "expires_at": "2026-01-01T00:00:00.000000Z",
  "success_url": "<string>",
  "return_url": "<string>",
  "embed_origin": "<string>",
  "amount": 123,
  "units": 123,
  "min_units": 123,
  "max_units": 123,
  "discount_amount": 123,
  "net_amount": 123,
  "tax_amount": 123,
  "tax_behavior": "inclusive",
  "total_amount": 123,
  "currency": "<string>",
  "allow_trial": true,
  "active_trial_interval": "day",
  "active_trial_interval_count": 123,
  "trial_end": "2026-01-01T00:00:00.000000Z",
  "organization_id": "<string>",
  "product_id": "<string>",
  "discount_id": "<string>",
  "allow_discount_codes": true,
  "require_billing_address": 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>",
  "is_business_customer": true,
  "customer_name": "<string>",
  "customer_email": "<string>",
  "customer_ip_address": "<string>",
  "customer_billing_name": "<string>",
  "customer_billing_address": {
    "country": "US",
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "customer_tax_id": "<string>",
  "payment_method_type": "<string>",
  "payment_processor_metadata": {},
  "billing_address_fields": {
    "country": "required",
    "state": "required",
    "city": "required",
    "postal_code": "required",
    "line1": "required",
    "line2": "required"
  },
  "trial_interval": "day",
  "trial_interval_count": 123,
  "metadata": {},
  "external_customer_id": "<string>",
  "products": [
    {
      "id": "<string>",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "trial_interval": "day",
      "trial_interval_count": 123,
      "name": "<string>",
      "description": "<string>",
      "visibility": "draft",
      "recurring_interval": "day",
      "recurring_interval_count": 123,
      "meter_interval": "day",
      "meter_interval_count": 123,
      "is_recurring": true,
      "is_archived": true,
      "organization_id": "<string>",
      "catalog_id": "<string>",
      "is_current": true,
      "prices": [
        {
          "created_at": "2026-01-01T00:00:00.000000Z",
          "modified_at": "2026-01-01T00:00:00.000000Z",
          "id": "<string>",
          "source": "catalog",
          "amount_type": "fixed",
          "price_currency": "<string>",
          "tax_behavior": "location",
          "is_archived": true,
          "product_id": "<string>",
          "price_amount": 123
        }
      ],
      "benefits": [
        {
          "id": "<string>",
          "created_at": "2026-01-01T00:00:00.000000Z",
          "modified_at": "2026-01-01T00:00:00.000000Z",
          "type": "custom",
          "description": "<string>",
          "selectable": true,
          "deletable": true,
          "is_deleted": 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": "2026-01-01T00:00:00.000000Z",
          "version": "<string>",
          "service": "product_media",
          "is_uploaded": true,
          "created_at": "2026-01-01T00:00:00.000000Z",
          "size_readable": "<string>",
          "public_url": "<string>"
        }
      ]
    }
  ],
  "product": {
    "id": "<string>",
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "trial_interval": "day",
    "trial_interval_count": 123,
    "name": "<string>",
    "description": "<string>",
    "visibility": "draft",
    "recurring_interval": "day",
    "recurring_interval_count": 123,
    "meter_interval": "day",
    "meter_interval_count": 123,
    "is_recurring": true,
    "is_archived": true,
    "organization_id": "<string>",
    "catalog_id": "<string>",
    "is_current": true,
    "prices": [
      {
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "id": "<string>",
        "source": "catalog",
        "amount_type": "fixed",
        "price_currency": "<string>",
        "tax_behavior": "location",
        "is_archived": true,
        "product_id": "<string>",
        "price_amount": 123
      }
    ],
    "benefits": [
      {
        "id": "<string>",
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "type": "custom",
        "description": "<string>",
        "selectable": true,
        "deletable": true,
        "is_deleted": 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": "2026-01-01T00:00:00.000000Z",
        "version": "<string>",
        "service": "product_media",
        "is_uploaded": true,
        "created_at": "2026-01-01T00:00:00.000000Z",
        "size_readable": "<string>",
        "public_url": "<string>"
      }
    ]
  },
  "product_price": {
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "id": "<string>",
    "source": "catalog",
    "amount_type": "fixed",
    "price_currency": "<string>",
    "tax_behavior": "location",
    "is_archived": true,
    "product_id": "<string>",
    "price_amount": 123
  },
  "prices": {},
  "discount": {
    "duration": "once",
    "type": "fixed",
    "amounts": {
      "eur": 900,
      "usd": 1000
    },
    "id": "<string>",
    "name": "<string>",
    "code": "<string>"
  },
  "subscription_id": "<string>",
  "attached_custom_fields": [
    {
      "custom_field_id": "<string>",
      "custom_field": {
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "id": "<string>",
        "metadata": {},
        "type": "text",
        "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": 1073741823,
          "max_length": 1073741823
        }
      },
      "order": 123,
      "required": true
    }
  ],
  "customer_metadata": {},
  "custom_field_data": {},
  "seats": 123,
  "min_seats": 123,
  "max_seats": 123,
  "locale": "<string>"
}

{
  "error": "AlreadyActiveSubscriptionError",
  "detail": "<string>"
}

{
  "error": "ResourceNotFound",
  "detail": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

General

Core API

Customer Portal API

Webhook Events

Integrations

Update Checkout Session

Authorizations

Scopes

Path Parameters

Body

Response