Get product information for subscription items

What's new?

We updated the subscription entity, so that subscription.items[] now returns a product object containing the related product entity.

How it works

A complete product in Paddle is made up of a product entity and a related price entity. Products describe items customers purchase, and prices describe how you bill for them.

When working with subscriptions, Paddle returns a price object for each item. You can use this to get information about the price of an item.

Previously, to get the related product for a price, you'd need to make another call to the Paddle API. With this release, we return the product object for each item too. This means you can present information like product name, image, description, and other data in your frontend when working with subscription entities.

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

Summary of changes

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

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