Work with lists

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 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.

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:

{
  "items": [
    {
      "price_id": "pri_01",
      "quantity": 80
    },
    {
      "price_id": "pri_02",
      "quantity": 1
    }
  ]
}

{
  "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
    }
  ]
}

If you include a price entity, Paddle creates a non-catalog price instead of relating the transaction to an existing price.