​
2025-06-18

​
Checkout API and Customer Session API changes

To be more consistent across our API, we’ve renamed customer_external_id field to external_customer_id in the Checkout API and Customer Session API.

  • Deprecated: customer_external_id field in the Checkout API and Customer Session API. Use external_customer_id instead.

​
Benefit metadata in Customer State

The customer state now includes the benefit metadata in the granted_benefits list.

​
2025-06-17

​
Webhook API endpoints are now documented

The API endpoints for managing webhooks are now documented in the API reference, and fully supported in our SDK.

Read more

​
2025-06-05

​
Rate limits

To ensure fair usage and maintain performance, we’ve introduced rate limits for the API. The limits are as follows:

  • 100 requests per second per IP address.
​
2025-06-02

​
Order invoice generation and retrieval

Until now, the invoice was generated automatically when the order was created, allowing you to call GET /v1/orders/{id}/invoice and GET /v1/customer-portal/orders/{id}/invoice endpoints without any prior action.

We now require you to explicitly generate the invoice by calling the POST /v1/orders/{id}/invoice or POST /v1/customer-portal/orders/{id}/invoice endpoints.

This change allows us to better handle the invoice generation process, and to allow the customer to change the billing details (name and address) before generating the invoice. This can be done through the PATCH /v1/orders/{id} or PATCH /v1/customer-portal/orders/{id} endpoints.

​
2025-04-16

​
Benefit metadata support and floating point numbers in metadata

  • Added: Benefits now support metadata.
  • Added: Metadata values now support floating-point numbers. Before, only strings, integers and booleans were supported.
​
2025-03-25

​
Checkout amount fields changes and depreciations

To be more consistent with the Order schema changes, we’ve made some changes to the field related to amounts in the Checkout schema.

​
2025-03-20

​
New order status and webhooks

Until now, Polar only kept track of fully processed, paid orders. To help you keep track of the order lifecycle, we’ve added a new status pending, which is a transitive state meaning the order is created but not paid yet. In most cases, the order will transition from pending to paid in a short time.

  • When receiving order.created event, the order status might not be paid.
  • Added: order.updated webhook, sent when the order status changes or when it’s partially or fully refunded.
  • Added: order.paid webhook, sent when the order is fully processed and paid.
  • Added: Order.paid property to the order schema.

If you were relying on the order.created webhook to keep track of succesful orders, we recommend you to switch to order.paid.

​
2025-03-14

​
Subscriptions and Orders schema changes

To prepare our next move to support usage-based billing, we’ve made some changes to the Subscription and Order schemas. The main reason behind those is that we need to support multiple prices and items in a single subscription or order.

  • Deprecated: Subscription.price_id and Subscription.price. Use the Subscription.prices array instead.
  • Deprecated: Order.product_price_id and Order.product_price. Use the Order.items array instead.
  • Deprecated: Order.amount. Use the Order.net_amount instead. It has the same value and meaning, but the new name is more explicit.
  • Added: Order.subtotal_amount, Order.discount_amount, and Order.total_amount fields to provide a more detailed breakdown of the order amount.