> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt). # 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: - [Products](https://developer.paddle.com/api-reference/products.md) have related [prices](https://developer.paddle.com/api-reference/prices.md) that describe how they're billed. - [Subscriptions](https://developer.paddle.com/api-reference/subscriptions.md) generate related [transactions](https://developer.paddle.com/api-reference/transactions.md) for subscription lifecycle events. - [Transactions](https://developer.paddle.com/api-reference/transactions.md) link to [customers](https://developer.paddle.com/api-reference/customers.md), [addresses](https://developer.paddle.com/api-reference/addresses.md), and [businesses](https://developer.paddle.com/api-reference/businesses.md) for billing. You can get information about related entities in two ways: - **Make separate requests** After getting an entity, extract the Paddle ID of a related entity and make a separate request to the API. - **Return entities using the include parameter** Use the `include` parameter, where available, to get related entities in a single request. ## Make a separate request Responses from the API often include any related entity IDs. For example, Paddle returns a `product_id` when [getting a price](https://developer.paddle.com/api-reference/prices/get-price.md). {% api-example method="GET" path="/prices/{price_id}" %} ```json {% title="Response" highlightLines="4" collapse=true %} { "data": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "type": "standard", "description": "Monthly", "name": "Monthly (per seat)", "billing_cycle": { "interval": "month", "frequency": 1 }, "trial_period": null, "tax_mode": "account_setting", "unit_price": { "amount": "3000", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "status": "active", "quantity": { "minimum": 1, "maximum": 999 }, "import_meta": null, "created_at": "2023-02-23T13:55:22.538367Z", "updated_at": "2024-04-11T13:54:52.254748Z" }, "meta": { "request_id": "ad44ee69-87c9-4d43-9d51-6c2c701c94f6" } } ``` {% /api-example %} To get information about a related entity, make a new request using its ID. In the previous example, you can make a call to the `/products/{product_id}` endpoint to get `pro_01gsz4vmqbjk3x4vvtafffd540`. {% api-example method="GET" path="/products/{product_id}" %} ```json {% title="Response" highlightLines="3" collapse=true %} { "data": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "AeroEdit Pro", "tax_category": "standard", "type": "standard", "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.", "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png", "custom_data": { "features": { "aircraft_performance": true, "compliance_monitoring": true, "flight_log_management": true, "payment_by_invoice": false, "route_planning": true, "sso": false }, "suggested_addons": [ "pro_01h1vjes1y163xfj1rh1tkfb65", "pro_01gsz97mq9pa4fkyy0wqenepkz" ], "upgrade_description": "Move from Basic to Pro to take advantage of aircraft performance, advanced route planning, and compliance monitoring." }, "status": "active", "import_meta": null, "created_at": "2023-02-23T12:43:46.605Z", "updated_at": "2024-04-05T15:53:44.687Z" }, "meta": { "request_id": "ccb21d76-1e13-4a5e-afb8-0f4c9f20ac07" } } ``` {% /api-example %} In cases where entities have multiple related entities, like [transactions](https://developer.paddle.com/api-reference/transactions.md), 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 enrich responses with 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. ### Include the related product with a price When an entity can only be linked to one of a related entity, an object is returned. For example, a price can 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](https://developer.paddle.com/api-reference/prices/get-price.md). {% api-example method="GET" path="/prices/{price_id}?include=product" %} ```json {% title="Response" highlightLines="25-55" collapse=true %} { "data": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "type": "standard", "description": "Monthly", "name": "Monthly (per seat)", "billing_cycle": { "interval": "month", "frequency": 1 }, "trial_period": null, "tax_mode": "account_setting", "unit_price": { "amount": "3000", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "status": "active", "quantity": { "minimum": 1, "maximum": 999 }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "AeroEdit Pro", "tax_category": "standard", "type": "standard", "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.", "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png", "custom_data": { "features": { "aircraft_performance": true, "compliance_monitoring": true, "flight_log_management": true, "payment_by_invoice": false, "route_planning": true, "sso": false }, "suggested_addons": [ "pro_01h1vjes1y163xfj1rh1tkfb65", "pro_01gsz97mq9pa4fkyy0wqenepkz" ], "upgrade_description": "Move from Basic to Pro to take advantage of aircraft performance, advanced route planning, and compliance monitoring." }, "status": "active", "import_meta": null, "created_at": "2023-02-23T12:43:46.605Z", "updated_at": "2024-04-05T15:53:44.687Z" }, "import_meta": null, "created_at": "2023-02-23T13:55:22.538367Z", "updated_at": "2024-04-11T13:54:52.254748Z" }, "meta": { "request_id": "60e33d17-0764-42ad-b538-c2b1f1231aef" } } ``` {% /api-example %} ### Include related prices with a product When an entity can be linked to more than one of a related entity, an array is returned. For example, products can have multiple prices. Paddle returns a `prices` object as part of the product `data` object. This example includes related prices when [getting a product](https://developer.paddle.com/api-reference/products/get-product.md). {% api-example method="GET" path="/products/{product_id}?include=prices" %} ```json {% title="Response" highlightLines="25-80" collapse=true %} { "data": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "AeroEdit Pro", "tax_category": "standard", "type": "standard", "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.", "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png", "custom_data": { "features": { "aircraft_performance": true, "compliance_monitoring": true, "flight_log_management": true, "payment_by_invoice": false, "route_planning": true, "sso": false }, "suggested_addons": [ "pro_01h1vjes1y163xfj1rh1tkfb65", "pro_01gsz97mq9pa4fkyy0wqenepkz" ], "upgrade_description": "Move from Basic to Pro to take advantage of aircraft performance, advanced route planning, and compliance monitoring." }, "status": "active", "prices": [ { "id": "pri_01gsz8z1q1n00f12qt82y31smh", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "type": "standard", "description": "Annual", "name": "Annual (per seat)", "billing_cycle": { "interval": "year", "frequency": 1 }, "trial_period": null, "tax_mode": "account_setting", "unit_price": { "amount": "30000", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "status": "active", "quantity": { "minimum": 1, "maximum": 999 }, "import_meta": null, "created_at": "2023-02-23T13:56:20.833019Z", "updated_at": "2024-04-11T13:47:49.566301Z" }, { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "type": "standard", "description": "Monthly", "name": "Monthly (per seat)", "billing_cycle": { "interval": "month", "frequency": 1 }, "trial_period": null, "tax_mode": "account_setting", "unit_price": { "amount": "3000", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "status": "active", "quantity": { "minimum": 1, "maximum": 999 }, "import_meta": null, "created_at": "2023-02-23T13:55:22.538367Z", "updated_at": "2024-04-11T13:54:52.254748Z" } ], "import_meta": null, "created_at": "2023-02-23T12:43:46.605Z", "updated_at": "2024-04-05T15:53:44.687Z" }, "meta": { "request_id": "b0c50f83-02d3-48d9-8a96-7011d4a9b3d0" } } ``` {% /api-example %} 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. {% callout type="info" %} If you try to `include` an entity that isn't supported, Paddle returns [an error](https://developer.paddle.com/api-reference/about/errors.md). {% /callout %}