Docs

List prices

Returns a paginated list of prices.

GET /prices

Returns a paginated list of prices. Use the query parameters to page through results.

By default, Paddle returns prices that are active. Use the status query parameter to return prices that are archived.

Use the include parameter to include the related product entity in the response.

Requires price.read permission.

Query parameters

idarray
Return only the IDs specified. Use a comma-separated list to get multiple entities.
afterstring
Return entities after the specified Paddle ID when working with paginated endpoints. Used in the meta.pagination.next URL in responses for list operations.
per_pageinteger
Default: 50

Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check meta.pagination.per_page in the response to see how many were returned.

Default: 50; Maximum: 200.

Max: 200
includearray
Include related entities in the response.
Values
  • product
    Include an object with the product related to this price.
order_bystring
Default: id[DESC]

Order returned entities by the specified field and direction ([ASC] or [DESC]). For example, ?order_by=id[ASC].

Valid fields for ordering: billing_cycle.frequency, billing_cycle.interval, id, product_id, quantity.maximum, quantity.minimum, status, tax_mode, unit_price.amount, and unit_price.currency_code.

product_idarray
Return entities related to the specified product. Use a comma-separated list to specify multiple product IDs.
statusarray
Default: active
Return entities that match the specified status. Use a comma-separated list to specify multiple status values.
Values
  • active
    Return entities where the status is active. Returned entities can be used in Paddle and are returned when listing entities.
  • archived
    Return entities where the status is archived. Returned entities can't be used for billing and aren't returned when listing entities.
recurringboolean
Determine whether returned entities are for recurring prices (true) or one-time prices (false).
billing_cycle.intervalstring
Return entities where the price billing cycle interval matches this value.
Values
  • day
  • week
  • month
  • year
billing_cycle.frequencyinteger
Return entities where the price billing cycle frequency matches this value.
Min: 1
typestring
Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.
Values
  • custom
    Return items where the type is custom. Returned items can be considered non-catalog items. They're typically created for a specific transaction or subscription. Not returned when listing via API or shown in the Paddle dashboard.
  • standard
    Return items where the type is standard. Returned items can be considered part of your catalog and reused across transactions and subscriptions easily.

Response (200)

dataarrayrequired
idstringrequired
Example: pri_01gsz8z1q1n00f12qt82y31smh
Unique Paddle ID for this price, prefixed with pri_.
Pattern: ^pri_[a-z\d]{26}$
product_idstringrequired
Example: pro_01gsz97mq9pa4fkyy0wqenepkz
Paddle ID for the product that this price is for, prefixed with pro_.
Pattern: ^pro_[a-z\d]{26}$
descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
typestringrequired
Default: standard
Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.
Values
  • custom
    Non-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.
  • standard
    Standard item. Can be considered part of your catalog and reused across transactions and subscriptions easily.
namestring | nullrequired
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | nullrequired
How often this price should be charged. null if price is non-recurring (one-time).
intervalstringrequired
Unit of time.
Values
  • day
  • week
  • month
  • year
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | nullrequired
Trial period for the product related to this price. The billing cycle begins once the trial period is over. null for no trial period. Requires billing_cycle.
intervalstringrequired
Unit of time.
Values
  • day
  • week
  • month
  • year
frequencyintegerrequired
Amount of time.
Min: 1
requires_payment_methodbooleanrequired
Default: true
Whether this price requires a payment method (true) or not (false) when trialing. If false, customers can sign up for subscription without entering their payment details, often referred to as a "cardless trial."
tax_modestringrequired
Default: account_setting
How tax is calculated for this price.
Values
  • account_setting
    Prices use the setting from your account.
  • external
    Prices are exclusive of tax.
  • internal
    Prices are inclusive of tax.
  • location
    Prices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have unit_price_overrides.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
unit_price_overridesarrayrequired
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
quantityobjectrequired
Example: {"minimum":1,"maximum":100}
Limits on how many times the related product can be purchased at this price. Useful for discount campaigns.
minimumintegerrequired
Default: 1
Example: 1
Minimum quantity of the product related to this price that can be bought. Required if maximum set.
Range: 1–999999999
maximumintegerrequired
Default: 100
Example: 100
Maximum quantity of the product related to this price that can be bought. Required if minimum set. Must be greater than or equal to the minimum value.
Range: 1–999999999
statusstringrequired
Default: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
custom_dataobject | nullrequired
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
import_metaobject | nullrequired
Import information for this entity. null if this entity is not imported.
external_idstring | null
Example: 9b95b0b8-e10f-441a-862e-1936a6d818ab
Reference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example: paddle_classic
Name of the platform or provider where this entity was imported from.
Length: 1–200
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
productobject
Related product for this price. Returned when the include parameter is used with the product value.
idstringrequired
Example: pro_01gsz97mq9pa4fkyy0wqenepkz
Unique Paddle ID for this product, prefixed with pro_.
Pattern: ^pro_[a-z\d]{26}$
namestringrequired
Name of this product.
Length: 1–200
descriptionstring | nullrequired
Short description for this product.
Max length: 2048
typestringrequired
Default: standard
Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.
Values
  • custom
    Non-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.
  • standard
    Standard item. Can be considered part of your catalog and reused across transactions and subscriptions easily.
tax_categorystringrequired
Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled on your Paddle account.
Values
  • digital-goods
    Non-customizable digital files or media (not software) acquired with an up front payment that can be accessed without any physical product being delivered.
  • ebooks
    Digital books and educational material which is sold with permanent rights for use by the customer.
  • implementation-services
    Remote configuration, set-up, and integrating software on behalf of a customer.
  • professional-services
    Services that involve the application of your expertise and specialized knowledge of a software product.
  • saas
    Products that allow users to connect to and use online or cloud-based applications over the Internet.
+ Show all values
  • software-programming-services
  • standard
    Software products that are pre-written and can be downloaded and installed onto a local device.
  • training-services
    Training and education services related to software products.
  • website-hosting
    Cloud storage service for personal or corporate information, assets, or intellectual property.
image_urlrequired
Image for this product. Included in the checkout and on some customer documents.
Image Url
A URL to an image.
null
Empty String
custom_dataobject | nullrequired
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
statusstringrequired
Default: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
import_metaobject | nullrequired
Import information for this entity. null if this entity is not imported.
external_idstring | null
Example: 9b95b0b8-e10f-441a-862e-1936a6d818ab
Reference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example: paddle_classic
Name of the platform or provider where this entity was imported from.
Length: 1–200
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
paginationobjectrequired
Keys used for working with paginated results.
per_pageintegerrequired
Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
nextstring (uri)required
URL containing the query parameters of the original request, along with the after parameter that marks the starting point of the next page. Always returned, even if has_more is false.
has_morebooleanrequired
Whether this response has another page.
estimated_totalinteger
Example: 999
Estimated number of entities for this response.
Response
{
  "data": [
    {
      "id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
      "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
      "type": "standard",
      "description": "Annual",
      "name": "Annual (recurring addon)",
      "billing_cycle": {
        "interval": "year",
        "frequency": 1
      },
      "trial_period": null,
      "tax_mode": "account_setting",
      "unit_price": {
        "amount": "100000",
        "currency_code": "USD"
      },
      "unit_price_overrides": [],
      "custom_data": null,
      "status": "active",
      "quantity": {
        "minimum": 1,
        "maximum": 1
      },
      "import_meta": null,
      "created_at": "2023-06-01T13:31:34.071379Z",
      "updated_at": "2024-04-05T14:33:40.972651Z"
    },
    {
      "id": "pri_01h1vjfevh5etwq3rb416a23h2",
      "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
      "type": "standard",
      "description": "Monthly",
      "name": "Monthly (recurring addon)",
      "billing_cycle": {
        "interval": "month",
        "frequency": 1
      },
      "trial_period": null,
      "tax_mode": "account_setting",
      "unit_price": {
        "amount": "10000",
        "currency_code": "USD"
      },
      "unit_price_overrides": [],
      "custom_data": null,
      "status": "active",
      "quantity": {
        "minimum": 1,
        "maximum": 100
      },
      "import_meta": null,
      "created_at": "2023-06-01T13:31:12.625056Z",
      "updated_at": "2024-04-09T07:23:00.907834Z"
    },
    {
      "id": "pri_01gvne87kv8vbqa9jkfbmgtsed",
      "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
      "type": "standard",
      "description": "Monthly",
      "name": "Monthly (per seat)",
      "billing_cycle": {
        "interval": "month",
        "frequency": 1
      },
      "trial_period": null,
      "tax_mode": "account_setting",
      "unit_price": {
        "amount": "5000",
        "currency_code": "USD"
      },
      "unit_price_overrides": [],
      "custom_data": null,
      "status": "active",
      "quantity": {
        "minimum": 1,
        "maximum": 100
      },
      "import_meta": null,
      "created_at": "2023-03-16T14:47:43.995985Z",
      "updated_at": "2024-04-09T07:29:19.91977Z"
    },
    {
      "id": "pri_01gsz98e27ak2tyhexptwc58yk",
      "product_id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
      "type": "standard",
      "description": "One-time addon",
      "name": "One-time addon",
      "billing_cycle": null,
      "trial_period": null,
      "tax_mode": "account_setting",
      "unit_price": {
        "amount": "19900",
        "currency_code": "USD"
      },
      "unit_price_overrides": [],
      "custom_data": null,
      "status": "active",
      "quantity": {
        "minimum": 1,
        "maximum": 1
      },
      "import_meta": null,
      "created_at": "2023-02-23T14:01:28.391712Z",
      "updated_at": "2024-04-09T07:23:10.921392Z"
    },
    {
      "id": "pri_01gsz96z29d88jrmsf2ztbfgjg",
      "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
      "type": "standard",
      "description": "Annual (recurring addon)",
      "name": "Annual (recurring addon)",
      "billing_cycle": {
        "interval": "year",
        "frequency": 1
      },
      "trial_period": null,
      "tax_mode": "account_setting",
      "unit_price": {
        "amount": "300000",
        "currency_code": "USD"
      },
      "unit_price_overrides": [],
      "custom_data": null,
      "status": "active",
      "quantity": {
        "minimum": 1,
        "maximum": 1
      },
      "import_meta": null,
      "created_at": "2023-02-23T14:00:40.265185Z",
      "updated_at": "2024-03-25T14:31:18.587603Z"
    },
    {
      "id": "pri_01gsz95g2zrkagg294kpstx54r",
      "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
      "type": "standard",
      "description": "Monthly (recurring addon)",
      "name": "Monthly (recurring addon)",
      "billing_cycle": {
        "interval": "month",
        "frequency": 1
      },
      "trial_period": null,
      "tax_mode": "account_setting",
      "unit_price": {
        "amount": "25000",
        "currency_code": "USD"
      },
      "unit_price_overrides": [],
      "custom_data": null,
      "status": "active",
      "quantity": {
        "minimum": 1,
        "maximum": 1
      },
      "import_meta": null,
      "created_at": "2023-02-23T13:59:52.159927Z",
      "updated_at": "2024-04-09T07:27:48.018296Z"
    },
    {
      "id": "pri_01gsz91wy9k1yn7kx82aafwvea",
      "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
      "type": "standard",
      "description": "Annual",
      "name": "Annual (per seat)",
      "billing_cycle": {
        "interval": "year",
        "frequency": 1
      },
      "trial_period": null,
      "tax_mode": "account_setting",
      "unit_price": {
        "amount": "50000",
        "currency_code": "USD"
      },
      "unit_price_overrides": [],
      "custom_data": null,
      "status": "active",
      "quantity": {
        "minimum": 1,
        "maximum": 100
      },
      "import_meta": null,
      "created_at": "2023-02-23T13:57:54.249913Z",
      "updated_at": "2024-04-05T14:32:00.471447Z"
    },
    {
      "id": "pri_01gsz8z1q1n00f12qt82y31smh",
      "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
      "type": "standard",
      "description": "Annual",
      "name": "Annual (per seat)",
      "billing_cycle": {
        "interval": "year",
        "frequency": 1
      },
      "trial_period": null,
      "tax_mode": "account_setting",
      "unit_price": {
        "amount": "30000",
        "currency_code": "USD"
      },
      "unit_price_overrides": [],
      "custom_data": null,
      "status": "active",
      "quantity": {
        "minimum": 1,
        "maximum": 999
      },
      "import_meta": null,
      "created_at": "2023-02-23T13:56:20.833019Z",
      "updated_at": "2024-04-11T13:47:49.566301Z"
    },
    {
      "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
      "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
      "type": "standard",
      "description": "Monthly",
      "name": "Monthly (per seat)",
      "billing_cycle": {
        "interval": "month",
        "frequency": 1
      },
      "trial_period": null,
      "tax_mode": "account_setting",
      "unit_price": {
        "amount": "3000",
        "currency_code": "USD"
      },
      "unit_price_overrides": [],
      "custom_data": null,
      "status": "active",
      "quantity": {
        "minimum": 1,
        "maximum": 999
      },
      "import_meta": null,
      "created_at": "2023-02-23T13:55:22.538367Z",
      "updated_at": "2024-04-11T13:54:52.254748Z"
    },
    {
      "id": "pri_01gsz8s48pyr4mbhvv2xfggesg",
      "product_id": "pro_01gsz4s0w61y0pp88528f1wvvb",
      "type": "standard",
      "description": "Annual",
      "name": "Annual (per seat)",
      "billing_cycle": {
        "interval": "year",
        "frequency": 1
      },
      "trial_period": null,
      "tax_mode": "account_setting",
      "unit_price": {
        "amount": "10000",
        "currency_code": "USD"
      },
      "unit_price_overrides": [],
      "custom_data": null,
      "status": "active",
      "quantity": {
        "minimum": 1,
        "maximum": 100
      },
      "import_meta": null,
      "created_at": "2023-02-23T13:53:06.838342Z",
      "updated_at": "2024-04-09T07:24:33.205169Z"
    },
    {
      "id": "pri_01gsz8ntc6z7npqqp6j4ys0w1w",
      "product_id": "pro_01gsz4s0w61y0pp88528f1wvvb",
      "type": "standard",
      "description": "Monthly",
      "name": "Monthly (per seat)",
      "billing_cycle": {
        "interval": "month",
        "frequency": 1
      },
      "trial_period": null,
      "tax_mode": "account_setting",
      "unit_price": {
        "amount": "1000",
        "currency_code": "USD"
      },
      "unit_price_overrides": [],
      "custom_data": null,
      "status": "active",
      "quantity": {
        "minimum": 1,
        "maximum": 100
      },
      "import_meta": null,
      "created_at": "2023-02-23T13:51:18.406674Z",
      "updated_at": "2024-04-05T14:29:40.000454Z"
    }
  ],
  "meta": {
    "request_id": "f44951b7-d24c-42cd-9477-57e659822674",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/prices?after=pri_01gsz8ntc6z7npqqp6j4ys0w1w",
      "has_more": false,
      "estimated_total": 1
    }
  }
}

Was this page helpful?