Orders

June 8, 2026 · View on GitHub

(orders)

Overview

Available Operations

list - List Orders
create - Create Order
export - Export Orders
get - Get Order
update - Update Order
finalize - Finalize Order
generate_invoice - Generate Order Invoice
invoice - Get Order Invoice
receipt - Get Order Receipt

list

List orders.

Scopes: orders:read

Example Usage

from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.orders.list(organization_id="1dbfc517-0bbf-4301-9ba8-555ca42b9737", page=1, limit=10)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter	Type	Required	Description
`organization_id`	OptionalNullable[models.OrdersListQueryParamOrganizationIDFilter]	:heavy_minus_sign:	Filter by organization ID.
`product_id`	OptionalNullable[models.OrdersListQueryParamProductIDFilter]	:heavy_minus_sign:	Filter by product ID.
`product_billing_type`	OptionalNullable[models.ProductBillingTypeFilter]	:heavy_minus_sign:	Filter by product billing type. `recurring` will filter data corresponding to subscriptions creations or renewals. `one_time` will filter data corresponding to one-time purchases.
`discount_id`	OptionalNullable[models.QueryParamDiscountIDFilter]	:heavy_minus_sign:	Filter by discount ID.
`customer_id`	OptionalNullable[models.OrdersListQueryParamCustomerIDFilter]	:heavy_minus_sign:	Filter by customer ID.
`external_customer_id`	OptionalNullable[models.OrdersListQueryParamExternalCustomerIDFilter]	:heavy_minus_sign:	Filter by customer external ID.
`checkout_id`	OptionalNullable[models.CheckoutIDFilter]	:heavy_minus_sign:	Filter by checkout ID.
`subscription_id`	OptionalNullable[models.SubscriptionIDFilter]	:heavy_minus_sign:	Filter by subscription ID.
`page`	Optional[int]	:heavy_minus_sign:	Page number, defaults to 1.
`limit`	Optional[int]	:heavy_minus_sign:	Size of a page, defaults to 10. Maximum is 100.
`sorting`	List[models.OrderSortProperty]	:heavy_minus_sign:	Sorting criterion. Several criteria can be used simultaneously and will be applied in order. Add a minus sign `-` before the criteria name to sort by descending order.
`metadata`	Dict[str, models.MetadataQuery]	:heavy_minus_sign:	Filter by metadata key-value pairs. It uses the `deepObject` style, e.g. `?metadata[key]=value`.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Errors

Error Type	Status Code	Content Type
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

Create a draft order for an off-session charge against a saved payment method. The order is created with status=draft and no invoice number; call POST /v1/orders/{id}/finalize to attempt the charge.

The organization must have the off_session_charges_enabled feature flag.

Scopes: orders:write

Example Usage

from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.orders.create(request={
        "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
        "customer_id": "<value>",
        "product_id": "<value>",
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`request`	models.OrderCreate	:heavy_check_mark:	The request object to use for the request.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

models.Order

Errors

Error Type	Status Code	Content Type
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

export

Export orders as a CSV file.

Scopes: orders:read

Example Usage

from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.orders.export(organization_id=None)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`organization_id`	OptionalNullable[models.OrdersExportQueryParamOrganizationIDFilter]	:heavy_minus_sign:	Filter by organization ID.
`product_id`	OptionalNullable[models.OrdersExportQueryParamProductIDFilter]	:heavy_minus_sign:	Filter by product ID.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

models.OrdersExportResponse

Errors

Error Type	Status Code	Content Type
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

get

Get an order by ID.

Scopes: orders:read

Example Usage

from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.orders.get(id="<value>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`id`	str	:heavy_check_mark:	The order ID.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

models.Order

Errors

Error Type	Status Code	Content Type
models.ResourceNotFound	404	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

update

Update an order.

Scopes: orders:write

Example Usage

import polar_sdk
from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.orders.update(id="<value>", order_update={
        "billing_address": {
            "country": polar_sdk.AddressInputCountryAlpha2Input.US,
        },
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`id`	str	:heavy_check_mark:	The order ID.
`order_update`	models.OrderUpdate	:heavy_check_mark:	N/A
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

models.Order

Errors

Error Type	Status Code	Content Type
models.ResourceNotFound	404	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

finalize

Finalize a draft order and synchronously attempt an off-session charge.

On success, the order transitions to paid and benefit grants fire before the response returns. On failure (decline, missing payment method, SCA challenge), the order stays in draft and a 4xx error is returned.

The request fails with 412 if the order is not in draft status.

Scopes: orders:write

Example Usage

from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.orders.finalize(id="<value>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`id`	str	:heavy_check_mark:	The order ID.
`order_finalize`	Optional[models.OrderFinalize]	:heavy_minus_sign:	N/A
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

models.Order

Errors

Error Type	Status Code	Content Type
models.PaymentFailed	402	application/json
models.PaymentActionRequired	402	application/json
models.OffSessionChargesNotEnabled	403	application/json
models.OrganizationNotReadyForPayments	403	application/json
models.ResourceNotFound	404	application/json
models.OrderNotDraft	412	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

generate_invoice

Trigger generation of an order's invoice.

Scopes: orders:read

Example Usage

from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.orders.generate_invoice(id="<value>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`id`	str	:heavy_check_mark:	The order ID.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

Any

Errors

Error Type	Status Code	Content Type
models.MissingInvoiceBillingDetails	422	application/json
models.NotPaidOrder	422	application/json
models.SDKError	4XX, 5XX	/

invoice

Get an order's invoice data.

Scopes: orders:read

Example Usage

from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.orders.invoice(id="<value>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`id`	str	:heavy_check_mark:	The order ID.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

models.OrderInvoice

Errors

Error Type	Status Code	Content Type
models.ResourceNotFound	404	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

receipt

Get a presigned URL to download an order's receipt PDF.

Scopes: orders:read

Example Usage

from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.orders.receipt(id="<value>")

    assert res is not None

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`id`	str	:heavy_check_mark:	The order ID.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

models.OrderReceipt

Errors

Error Type	Status Code	Content Type
models.ResourceNotFound	404	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/