Related entities

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

• Products have related prices that describe how they're billed.
• Subscriptions generate related transactions for subscription lifecycle events.
• Transactions link to customers, addresses, and businesses 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 sometimes include its related entity IDs. For example, Paddle returns a product_id when getting a price.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
4    "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
5    "type": "standard",
6    "description": "Monthly",
7    "name": "Monthly (per seat)",
8    "billing_cycle": {
9      "interval": "month",
10      "frequency": 1
11    },
12    "trial_period": null,
13    "tax_mode": "account_setting",
14    "unit_price": {
15      "amount": "3000",
16      "currency_code": "USD"
17    },
18    "unit_price_overrides": [],
19    "custom_data": null,
20    "status": "active",

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
4    "name": "AeroEdit Pro",
5    "tax_category": "standard",
6    "type": "standard",
7    "description": "Designed for professional pilots, including all features plus in Basic plus\ncompliance monitoring, route optimization, and third-party integrations.",
8    "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png",
9    "custom_data": {
10      "features": {
11        "aircraft_performance": true,
12        "compliance_monitoring": true,
13        "flight_log_management": true,
14        "payment_by_invoice": false,
15        "route_planning": true,
16        "sso": false
17      },
18      "suggested_addons": [
19        "pro_01h1vjes1y163xfj1rh1tkfb65",
20        "pro_01gsz97mq9pa4fkyy0wqenepkz"

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.

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
16      "currency_code": "USD"
17    },
18    "unit_price_overrides": [],
19    "custom_data": null,
20    "status": "active",
21    "quantity": {
22      "minimum": 1,
23      "maximum": 999
24    },
25    "product": {
26      "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
27      "name": "AeroEdit Pro",
28      "tax_category": "standard",
29      "type": "standard",
30      "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.",
31      "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png",
32      "custom_data": {
33        "features": {
34          "aircraft_performance": true,
35          "compliance_monitoring": true,

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