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

# API Changelog

> Stay up to date with the latest changes, improvements and deprecations to the Polar API.

<Update label="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.

  * <Icon icon="circle-exclamation" size={16} color="orange" /> **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](/api-reference/customers/state#response-benefit-metadata) in the `granted_benefits` list.
</Update>

<Update label="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](/api-reference/webhooks/endpoints/create)
</Update>

<Update label="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.
</Update>

<Update label="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`](/api-reference/orders/get-invoice) and [`GET /v1/customer-portal/orders/{id}/invoice`](/api-reference/customer-portal/orders/get-invoice) endpoints without any prior action.

  We now require you to explicitly generate the invoice by calling the [`POST /v1/orders/{id}/invoice`](/api-reference/orders/post-invoice) or [`POST /v1/customer-portal/orders/{id}/invoice`](/api-reference/customer-portal/orders/post-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}`](/api-reference/orders/patch) or [`PATCH /v1/customer-portal/orders/{id}`](/api-reference/customer-portal/orders/patch) endpoints.
</Update>

<Update label="2025-04-16">
  ## Benefit metadata support and floating point numbers in metadata

  * <Icon icon="check" size={16} color="green" /> **Added**: Benefits now support
    [metadata](/api-reference/benefits/create#body-metadata).
  * <Icon icon="check" size={16} color="green" /> **Added**: Metadata values now
    support floating-point numbers. Before, only strings, integers and booleans
    were supported.
</Update>

<Update label="2025-03-25">
  ## Checkout amount fields changes and depreciations

  To be more consistent with the [Order schema changes](#2025-03-14), we've made some changes to the field related to amounts in the Checkout schema.

  * <Icon icon="check" size={16} color="green" /> **Added**:
    [`checkout.discount_amount`](/api-reference/checkouts/get-session#response-discount-amount).
  * <Icon icon="check" size={16} color="green" /> **Added**:
    [`checkout.net_amount`](/api-reference/checkouts/get-session#response-net-amount).
  * <Icon icon="circle-exclamation" size={16} color="orange" /> **Deprecated**:
    `checkout.subtotal_amount`, use
    [`checkout.net_amount`](/api-reference/checkouts/get-session#response-net-amount)
    instead.
</Update>

<Update label="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.

  * <Icon icon="circle-exclamation" size={16} color="orange" /> When receiving
    `order.created` event, the order status might not be `paid`.
  * <Icon icon="check" size={16} color="green" /> **Added**:
    [`order.updated`](/api-reference/webhooks/order.updated) webhook, sent when
    the order status changes or when it's partially or fully refunded.
  * <Icon icon="check" size={16} color="green" /> **Added**:
    [`order.paid`](/api-reference/webhooks/order.paid) webhook, sent when the
    order is fully processed and paid.
  * <Icon icon="check" size={16} color="green" /> **Added**:
    [`Order.paid`](/api-reference/orders/get#response-paid) property to the order
    schema.

  <Info>
    If you were relying on the `order.created` webhook to keep track of succesful
    orders, we recommend you to switch to `order.paid`.
  </Info>
</Update>

<Update label="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`](/api-reference/subscriptions/get) and [`Order`](/api-reference/orders/get) schemas. The main reason behind those is that we need to support multiple prices and items in a single subscription or order.

  * <Icon icon="circle-exclamation" size={16} color="orange" /> **Deprecated**:
    `Subscription.price_id` and `Subscription.price`. Use the
    `Subscription.prices` array instead.
  * <Icon icon="circle-exclamation" size={16} color="orange" /> **Deprecated**:
    `Order.product_price_id` and `Order.product_price`. Use the `Order.items`
    array instead.
  * <Icon icon="circle-exclamation" size={16} color="orange" /> **Deprecated**:
    `Order.amount`. Use the `Order.net_amount` instead. It has the same value and
    meaning, but the new name is more explicit.
  * <Icon icon="check" size={16} color="green" /> **Added**:
    `Order.subtotal_amount`, `Order.discount_amount`, and `Order.total_amount`
    fields to provide a more detailed breakdown of the order amount.
</Update>