> ## Documentation Index
> Fetch the complete documentation index at: https://polar.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Orders
> Every paid transaction on Polar is an order.
An **order** is the record of a single paid transaction on Polar. Every successful checkout, subscription cycle, and subscription change generates an order — it's where the money, the tax, the invoice, and the link back to the [product](/features/products) and [customer](/features/customer-management) live.
If [subscriptions](/features/subscriptions/introduction) are the *relationship* with a customer, orders are the *individual payments* inside that relationship.
## When orders are created
Polar creates an order in all of these cases:
* **One-time purchase** — when a customer checks out a non-recurring product.
* **Subscription created** — the initial order generated when a customer subscribes.
* **Subscription renewal** — every billing cycle of an active subscription.
* **Subscription change** — when a plan or seat update is prorated with `invoice` behavior and charges the difference immediately. See [Proration](/features/subscriptions/proration).
Each order carries a `billing_reason` that tells you which of these it is: `purchase`, `subscription_create`, `subscription_cycle`, or `subscription_update`.
## Arbitrary charges
Sometimes you need to charge a customer an amount that doesn't originate from a checkout or a subscription renewal — a usage overage, a one-off professional-services fee, or a manual top-up. Polar lets you run these **off-session charges** against a customer's saved payment method, without the customer being present.
Off-session charges are currently in preview. You'll only be able to run off-session charges if
you are on a paid plan.
An off-session charge is a two-step flow: you create a **draft order**, then **finalize** it to attempt the charge. Both endpoints require the `orders:write` scope and the sales-management permission on the organization.
### 1. Create a draft order
`POST /v1/orders/` creates an order in `draft` status with no invoice number — nothing is charged yet. You reference an existing customer and a one-time product, and optionally override the amount and description:
| Field | Required | Description |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `customer_id` | Yes | The customer to charge. Must belong to the organization. |
| `product_id` | Yes | A one-time product to charge for. Only fixed-price and free products are supported. |
| `amount` | No | A custom amount in the smallest currency unit (e.g. `2500` for \$25.00). Overrides the product's price; defaults to it. |
| `currency` | No | ISO 4217, lowercase (e.g. `usd`). Defaults to the organization's currency. |
| `description` | No | The line-item text shown on the invoice and receipt. Defaults to the product name. |
| `organization_id` | No | Required unless you authenticate with an organization token. |
The customer must have a complete billing address (so Polar can calculate tax) and at least one saved payment method.
```bash cURL theme={null}
curl --request POST \
--url https://api.polar.sh/v1/orders/ \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"customer_id": "",
"product_id": "",
"amount": 2500,
"description": "5,000 extra tokens"
}'
```
The response is the draft order, including its `id`. Creating a draft fires the `order.created` webhook but does not yet email the customer.
### 2. Finalize and charge
`POST /v1/orders/{id}/finalize` synchronously attempts the off-session charge. By default it uses the customer's default payment method; pass `payment_method_id` to charge a specific one.
```bash cURL theme={null}
curl --request POST \
--url https://api.polar.sh/v1/orders//finalize \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{}'
```
On success, the order transitions to `paid`, an invoice number is assigned, any [benefits](/features/benefits/introduction) attached to the product are granted, the customer is emailed their confirmation, and the [`order.paid`](/api-reference/webhooks/order.paid) webhook fires.
If the charge fails, the API returns an error and the order is reverted to `draft` so you can fix the problem and finalize the same order again — no invoice number is consumed by a failed attempt:
| Status | When |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `402` | The card was declined, the customer has no payment method, or the charge needs a 3DS / SCA challenge that can't be completed off-session. |
| `403` | Off-session charges aren't enabled for the organization, or its account can't currently accept payments. |
| `412` | The order is no longer in `draft` status (for example, it was already finalized). |
## Order status
An order moves through a small set of statuses over its lifetime:
| Status | Meaning |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `pending` | The order has been created and Polar is attempting to collect payment. |
| `paid` | The payment succeeded. |
| `refunded` | The order has been fully refunded. |
| `partially_refunded` | Part of the order has been refunded. See [Refunds](/features/refunds). |
| `void` | The order will not be collected (for example, it's been voided after repeated failures). |
Free orders — those with a total of zero, typically from a \$0 subscription or a 100% discount — are marked `paid` immediately with no payment step.
## What's on an order
Every order carries:
* **Amounts**: subtotal, discount, tax, net, and total, with the currency it was billed in.
* **Billing details**: customer billing name and address (editable until the invoice is generated).
* **Tax details**: taxability reason, tax rate, and the amount collected — useful if you're operating as merchant of record on your own, or reconciling against Polar's [MoR tax handling](/merchant-of-record/introduction).
* **A link to the product and customer**, and to the subscription if the order came from a subscription.
* **The invoice**, once it's been generated.
* **[Custom field data](/features/custom-fields)** captured at checkout.
## Invoices
Polar generates a PDF invoice for every paid order. You can:
* **Download it** from the order detail page in the dashboard.
* **Trigger generation** programmatically via [Generate Order Invoice](/api-reference/orders/post-invoice), then fetch the URL with [Get Order Invoice](/api-reference/orders/get-invoice).
Customers can download and edit their own invoices — adding a company name, VAT number, or billing address — from the [Customer Portal](/features/customer-portal/introduction), without pulling you into a support thread.
Once an invoice has been generated, its billing details are frozen. If you need to correct a name
or address after the fact, the customer should edit their invoice from the Customer Portal, which
regenerates it.
## Receipts
A **receipt** is the proof of payment for an order — what was charged, how, and what's been refunded since. Polar issues one for every paid order and assigns a per-customer number in the form `RCPT-{customer-id}-{NNNN}`.
Each receipt includes:
* The **payment method** used (e.g. `Visa — 4242`), the **date paid**, and the **amount**.
* Any **customer balance** applied to the order.
* Any **refunds** issued against the order, with dates and amounts.
* The same line items, taxes, totals, and linked invoice number as the order's invoice.
Customers download receipts from the [Customer Portal](/features/customer-portal/introduction) — a **Download Receipt** button appears on each paid order. Programmatically, use [Get Order Receipt](/api-reference/orders/get-receipt) for the merchant API or its [customer-portal counterpart](/api-reference/customer-portal/orders/get-receipt).
The first request for a given order may return `202 Accepted` while the PDF renders. Retry shortly after for a presigned download URL. The Customer Portal handles this for you.
## Refunds
Orders can be refunded in full or in part from the dashboard, or programmatically via the [Refunds API](/api-reference/refunds/create). Refunds are a separate resource linked to the order — see [Refunds](/features/refunds) for the rules around what's refundable and how it interacts with payouts.
## Webhooks
If you're integrating orders into your own system, Polar emits an event on every state transition:
* [`order.created`](/api-reference/webhooks/order.created) — a new order exists (not necessarily paid yet).
* [`order.paid`](/api-reference/webhooks/order.paid) — the order has been collected. This is the one most integrations care about.
* [`order.updated`](/api-reference/webhooks/order.updated) — something changed on the order.
* [`order.refunded`](/api-reference/webhooks/order.refunded) — a refund was issued against the order.
## Next steps
The recurring relationship that generates most orders.
How to refund an order, fully or partially.
List and fetch orders, update billing details, and generate invoices.
Where customers view their own orders and download invoices and receipts.