> ## 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`.
## 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.