Lists
Some entities in the Paddle API have lists against them. When updating lists, send the complete list. Omitted items are removed from the list.
Some entities hold lists that you can work with. For example:
- Business entities have a list of contacts.
- Price entities have a list of price overrides.
- Subscription and transaction entities have a list of items.
When updating lists, send the complete list of items that should be in the list. Omitted items are considered deleted, and removed from the list.
Update lists
Updating lists works like a PUT request. You should send the complete list of items that you want to be against your entity — including any existing items.
This means that you should make a GET request to get existing items, then extract information about existing items from the response. Then, build an array that includes the existing items you want to retain, plus any new items that you want to add. Send a PATCH request with your array to update.
If you omit items, Paddle removes them from the list. Paddle sends the complete updated entity in response to successful PATCH requests, so you can check to see that your lists look as expected.
Work with lists of prices
When working with entities that have lists of items against them, like subscriptions and transactions, the items list is made up of price entities.
When creating or updating lists of prices against an entity, send a price ID and quantity rather than the complete price entity. If successful, Paddle returns the complete price entity. If you include a price entity, Paddle creates a non-catalog price instead of relating the transaction to an existing price.
When updating subscription items, you must send proration_billing_mode alongside your request to tell Paddle how to handle proration for the changes you made to the items.
Examples
Paddle IDs are simplified in the following examples to make them easier to follow. Paddle IDs for prices are made up of
pri_followed by 26 characters, for examplepri_01gsz98e27ak2tyhexptwc58yk.
In this example:
- The quantity of
pri_01is incremented from50to80. pri_02remains the same.
Before
This is the items list before any changes:
12345678910111213141516171819201{
2 "items": [
3 {
4 "price": {
5 "id": "pri_01",
6 "description": "Annual (per seat)",
7 "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
8 "billing_cycle": {
9 "interval": "year",
10 "frequency": 1
11 },
12 "trial_period": null,
13 "tax_mode": "account_setting",
14 "unit_price": {
15 "amount": "48000",
16 "currency_code": "USD"
17 },
18 "unit_price_overrides": [],
19 "quantity": {
20 "minimum": 1,
Request
To update a transaction, send an object for each item containing a price_id and a quantity.
Though this example only updates pri_01, it includes pri_02 and its original quantity so that it's retained on the transaction.
1234567891011121{
2 "items": [
3 {
4 "price_id": "pri_01",
5 "quantity": 80
6 },
7 {
8 "price_id": "pri_02",
9 "quantity": 1
10 }
11 ]
12}Response
When working with transactions, Paddle returns the complete price entity.
If pri_02 wasn't included with the request, it would be removed from the items list.
12345678910111213141516171819201{
2 "items": [
3 {
4 "price": {
5 "id": "pri_01",
6 "description": "Annual (per seat)",
7 "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
8 "billing_cycle": {
9 "interval": "year",
10 "frequency": 1
11 },
12 "trial_period": null,
13 "tax_mode": "account_setting",
14 "unit_price": {
15 "amount": "48000",
16 "currency_code": "USD"
17 },
18 "unit_price_overrides": [],
19 "quantity": {
20 "minimum": 1,
In this example:
pri_3is added to the items list.pri_1andpri_2remain the same.
Before
This is the items list before any changes:
12345678910111213141516171819201{
2 "items": [
3 {
4 "price": {
5 "id": "pri_01",
6 "description": "Annual (per seat)",
7 "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
8 "billing_cycle": {
9 "interval": "year",
10 "frequency": 1
11 },
12 "trial_period": null,
13 "tax_mode": "account_setting",
14 "unit_price": {
15 "amount": "48000",
16 "currency_code": "USD"
17 },
18 "unit_price_overrides": [],
19 "quantity": {
20 "minimum": 1,
Request
To update a transaction, send an object for each item containing a price_id and a quantity.
Though this example only adds pri_03, it includes pri_01 and pri_02 and their original quantities so that they're retained on the transaction.
123456789101112131415161{
2 "items": [
3 {
4 "price_id": "pri_01",
5 "quantity": 80
6 },
7 {
8 "price_id": "pri_02",
9 "quantity": 1
10 },
11 {
12 "price_id": "pri_03",
13 "quantity": 1
14 }
15 ]
16}Response
When working with transactions, Paddle returns the complete price entity.
If pri_01 and pri_02 weren't included with the request, they'd be removed from the items list.
12345678910111213141516171819201{
2 "items": [
3 {
4 "price": {
5 "id": "pri_01",
6 "description": "Annual (per seat)",
7 "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
8 "billing_cycle": {
9 "interval": "year",
10 "frequency": 1
11 },
12 "trial_period": null,
13 "tax_mode": "account_setting",
14 "unit_price": {
15 "amount": "48000",
16 "currency_code": "USD"
17 },
18 "unit_price_overrides": [],
19 "quantity": {
20 "minimum": 1,
In this example:
pri_2is removed from the items list.pri_1andpri_3remain the same.
Before
This is the items list before any changes:
12345678910111213141516171819201{
2 "items": [
3 {
4 "price": {
5 "id": "pri_01",
6 "description": "Annual (per seat)",
7 "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
8 "billing_cycle": {
9 "interval": "year",
10 "frequency": 1
11 },
12 "trial_period": null,
13 "tax_mode": "account_setting",
14 "unit_price": {
15 "amount": "48000",
16 "currency_code": "USD"
17 },
18 "unit_price_overrides": [],
19 "quantity": {
20 "minimum": 1,
Request
To update a transaction, send an object for each item containing a price_id and a quantity.
This example removes pri_02 by omitting it from the request. It includes pri_01 and pri_03 and their original quantities so that they're retained on the transaction.
1234567891011121{
2 "items": [
3 {
4 "price_id": "pri_01",
5 "quantity": 80
6 },
7 {
8 "price_id": "pri_03",
9 "quantity": 1
10 }
11 ]
12}Response
When working with transactions, Paddle returns the complete price entity.
As pri_02 wasn't included with the request, it's not part of the items list.
12345678910111213141516171819201{
2 "items": [
3 {
4 "price": {
5 "id": "pri_01",
6 "description": "Annual (per seat)",
7 "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
8 "billing_cycle": {
9 "interval": "year",
10 "frequency": 1
11 },
12 "trial_period": null,
13 "tax_mode": "account_setting",
14 "unit_price": {
15 "amount": "48000",
16 "currency_code": "USD"
17 },
18 "unit_price_overrides": [],
19 "quantity": {
20 "minimum": 1,
