> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Work with 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](https://developer.paddle.com/api-reference/businesses.md) entities have a list of contacts.
- [Price](https://developer.paddle.com/api-reference/prices.md) entities have a list of price overrides.
- [Subscription](https://developer.paddle.com/api-reference/subscriptions.md) and [transaction](https://developer.paddle.com/api-reference/transactions.md) 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 a list works like a `PUT` request. Send the complete list of items you want against the entity — including any existing items you want to keep.

To update a list:

1. Make a `GET` request to fetch existing items.
2. Extract the items you want to retain.
3. Build an array of existing items plus any new items you want to add.
4. Send a `PATCH` request with the complete array.

If you omit items, Paddle removes them from the list. Paddle returns the complete updated entity in response to successful `PATCH` requests, so you can check 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](https://developer.paddle.com/api-reference/prices.md).

When creating or updating lists of prices against an entity, send a price ID and quantity rather than the complete price entity to use an existing price. If successful, Paddle returns the complete price entity. For example:

{% api-example method="PATCH" path="/transactions/{transaction_id}" %}

```json {% title="Request" %}
{
  "items": [
    {
      "price_id": "pri_01",
      "quantity": 80
    },
    {
      "price_id": "pri_02",
      "quantity": 1
    }
  ]
}
```

```json {% title="Response" collapse=true %}
{
  "items": [
    {
      "price": {
        "id": "pri_01",
        "description": "Annual (per seat)",
        "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
        "billing_cycle": {
          "interval": "year",
          "frequency": 1
        },
        "trial_period": null,
        "tax_mode": "account_setting",
        "unit_price": {
          "amount": "48000",
          "currency_code": "USD"
        },
        "unit_price_overrides": [],
        "quantity": {
          "minimum": 1,
          "maximum": 100
        },
        "status": "active"
      },
      "quantity": 80
    },
    {
      "price": {
        "id": "pri_02",
        "description": "Annual (recurring addon)",
        "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
        "billing_cycle": {
          "interval": "year",
          "frequency": 1
        },
        "trial_period": null,
        "tax_mode": "account_setting",
        "unit_price": {
          "amount": "300000",
          "currency_code": "USD"
        },
        "unit_price_overrides": [],
        "quantity": {
          "minimum": 1,
          "maximum": 1
        },
        "status": "active"
      },
      "quantity": 1
    }
  ]
}
```

{% /api-example %}

If you include a price entity, Paddle creates [a non-catalog price](https://developer.paddle.com/build/transactions/bill-create-custom-items-prices-products.md) instead of relating the transaction to an existing price.

{% callout type="info" %}
When [updating subscription items](https://developer.paddle.com/build/subscriptions/add-remove-products-prices-addons.md), you must send `proration_billing_mode` alongside your request to tell Paddle [how to handle proration](https://developer.paddle.com/concepts/subscriptions/proration.md) for the changes you made to the items.
{% /callout %}