See the complete price entity for subscription items

What's new?

We updated the subscription entity, so that subscription.items[].price now returns all fields against a price entity, rather than a subset of fields.

How it works

When working with subscriptions, Paddle returns a price object for each item. You can use this to get information about a price without making another call to the Paddle API.

Previously, we returned a subset of fields against a price entity for subscription items. With this release, we return the complete price entity. This makes the behavior of subscription items consistent with other parts of the Paddle API, and means you have all the information about the price when working with subscription entities.

The price returned is a snapshot of the price at the time it was added to the subscription. If you update a price entity after it's added to a subscription, the price object returned for a subscription item doesn't include any changes since you added it.

Summary of changes

This is a summary of the changes to fields in the Paddle API and webhooks.

subscription.items[].price now returns a price entity. The following fields were not previously included:

Example

This example is a response for the get a subscription operation.

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": "sub_01hv8y5ehszzq0yv20ttx3166y",
4    "status": "active",
5    "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j",
6    "address_id": "add_01hv8y4jk511j9g2n9a2mexjbx",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2024-04-12T10:38:00.761Z",
10    "updated_at": "2024-04-12T10:38:00.761Z",
11    "started_at": "2024-04-12T10:37:59.556997Z",
12    "first_billed_at": "2024-04-12T10:37:59.556997Z",
13    "next_billed_at": "2024-05-12T10:37:59.556997Z",
14    "paused_at": null,
15    "canceled_at": null,
16    "collection_mode": "automatic",
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2024-04-12T10:37:59.556997Z",
20      "ends_at": "2024-05-12T10:37:59.556997Z"

Next steps

This change is available in version 1 of the Paddle API.

It's a non-breaking change, meaning it doesn't impact existing integrations.

You can list subscriptions using the API to check out the changes to subscription items.

Learn more