Paddle Billing

Related entities

Entities in Paddle relate to each other. Use the include query parameter to get related entities in a single query.

Entities in the Paddle API often relate to each other. For example:

There are two ways to get information about a related entity:

  1. Make a separate request for an entity.

  2. Use the include parameter, where available, to get related entities in a single request.

Make a separate request

Responses from the API sometimes include its related entity IDs. For example, Paddle returns a product_id when getting a price.

To get information about a related entity, make a new request using its ID. In the example above, we'd make a call to the /products/{product_id} endpoint to get pro_01gsz4vmqbjk3x4vvtafffd540.

In cases where entities have multiple related entities, like transactions, you might need to make more than one API call to get all related entities. This could have an impact on the performance of your integration.

Use include parameter

Rather than making multiple API calls, some operations let you get related entities using the include query parameter. This is generally more efficient as it requires fewer calls.

When including entities:

  • Paddle returns an object or an array with the included entities.
  • All related entities are returned, including archived entities.
  • Related entities aren't paginated.

When an entity may only be linked to one of a related entity, an object is returned. For example, a price may only be related to one product. Paddle returns a product object as part of the price data object.

This example includes the related product entity when getting a price.

You can include multiple entities using a comma separated list. Keep in mind that including multiple entities might result in longer response times and larger responses, which could impact performance.

If you try to include an entity that isn't supported, Paddle returns an error.

Related pages