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, you may send a price ID and quantity rather than the complete price entity. If successful, Paddle returns the complete price entity.
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
We've simplified price IDs in the following examples to make them easier to follow. Price IDs are made up of
pri_, followed by 26 characters. For example:pri_01gsz98e27ak2tyhexptwc58yk.See: Paddle IDs
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
When you update a transaction, send price_ids rather than price entities.
Though we're only updating pri_01, we included pri_02 and its original quantity.
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 you work with a transaction, Paddle responds with 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
When you update a transaction, send price_ids rather than price entities.
Though we're only adding pri_03, we included pri_01 and pri_02 and their original quantities.
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 you work with a transaction, Paddle responds with 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
When you update a transaction, send price_ids rather than price entities.
To remove pri_02, we omit it from the request. We included pri_01 and pri_02 and their original quantities.
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 you work with a transaction, Paddle responds with 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,
