Skip to main content

​
Overview

Orders represent completed purchases. They’re created when customers complete checkout sessions or when subscriptions renew.

​
The Order Object

​
id
string
required
Unique identifier for the order
​
status
enum
required
Status: pending, paid, refunded, or failed
​
customer_id
string
required
ID of the customer
​
product_id
string
required
ID of the product
​
product_price_id
string
required
ID of the price
​
subscription_id
string
Associated subscription ID (for recurring orders)
​
checkout_id
string
Associated checkout session ID
​
amount
integer
required
Total amount in cents
​
tax_amount
integer
required
Tax amount in cents
​
net_amount
integer
required
Net amount (after tax) in cents
​
currency
string
required
Three-letter ISO currency code
​
description
string
required
Order description
​
invoice_number
string
Invoice number
​
billing_address
object
Customer’s billing address
​
discount_id
string
Applied discount ID
​
metadata
object
Custom metadata
​
created_at
string
required
Creation timestamp

​
List Orders

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

​
Query Parameters

​
organization_id
string
Filter by organization
​
product_id
string
Filter by product
​
product_billing_type
enum
Filter by type: recurring (subscription renewals) or one_time
​
discount_id
string
Filter by discount
​
customer_id
string
Filter by customer
​
external_customer_id
string
Filter by external customer ID
​
checkout_id
string
Filter by checkout session
​
metadata
object
Filter by metadata

​
Get Order

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

​
Path Parameters

​
id
string
required
Order ID

​
Update Order

cURL
curl -X PATCH "https://api.polar.sh/v1/orders/{id}" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "fulfillment_status": "shipped"
    }
  }'

​
Path Parameters

​
id
string
required
Order ID

​
Request Body

​
metadata
object
Update metadata

​
Get Invoice

cURL
curl -X GET "https://api.polar.sh/v1/orders/{id}/invoice" \
  -H "Authorization: Bearer polar_pat_..."
Get the invoice data for an order.

​
Path Parameters

​
id
string
required
Order ID

​
Response

​
url
string
URL to download the invoice PDF
​
invoice_number
string
Invoice number

​
Generate Invoice

cURL
curl -X POST "https://api.polar.sh/v1/orders/{id}/invoice" \
  -H "Authorization: Bearer polar_pat_..."
Trigger invoice generation for an order.

​
Path Parameters

​
id
string
required
Order ID

​
Response

​
202
Accepted
Invoice generation started

​
Errors

​
422
Unprocessable Entity
Order is not paid or missing billing details

​
Export Orders

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

​
Query Parameters

​
organization_id
string
Filter by organization
​
product_id
string
Filter by product

​
Response

Returns a CSV file with order data.

​
Examples

​
Get Customer’s Orders

curl -X GET "https://api.polar.sh/v1/orders?customer_id=cust_123" \
  -H "Authorization: Bearer polar_pat_..."

​
Filter Subscription Orders

curl -X GET "https://api.polar.sh/v1/orders?product_billing_type=recurring" \
  -H "Authorization: Bearer polar_pat_..."

​
Update Order Metadata

curl -X PATCH "https://api.polar.sh/v1/orders/order_123" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "shipped_at": "2024-01-15T10:00:00Z",
      "tracking_number": "1Z999AA10123456784"
    }
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us