Paddle Billing


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:

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'd like 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'd like to retain, plus any new items that you'd like 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.


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

Related pages