Skip to main content
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 and customer live. If subscriptions 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.
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:
StatusMeaning
pendingThe order has been created and Polar is attempting to collect payment.
paidThe payment succeeded.
refundedThe order has been fully refunded.
partially_refundedPart of the order has been refunded. See Refunds.
voidThe 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.
  • 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 captured at checkout.

​
Invoices

Polar generates a PDF invoice for every paid order. You can: Customers can download and edit their own invoices — adding a company name, VAT number, or billing address — from the Customer Portal, 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.

​
Refunds

Orders can be refunded in full or in part from the dashboard, or programmatically via the Refunds API. Refunds are a separate resource linked to the order — see 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 — a new order exists (not necessarily paid yet).
  • order.paid — the order has been collected. This is the one most integrations care about.
  • order.updated — something changed on the order.
  • order.refunded — a refund was issued against the order.

​
Next steps

Subscriptions

The recurring relationship that generates most orders.

Refunds

How to refund an order, fully or partially.

Orders API

List and fetch orders, update billing details, and generate invoices.

Customer Portal

Where customers view their own orders and download invoices.