What's new?
We updated the subscription entity, so that subscription.items[] now returns a product object containing the related product entity.
items array
List of items on this subscription. Only recurring items are returned.
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.
Example
This example is a response for the get a subscription operation.
GET
/subscriptions/{subscription_id} { "data": { "id": "sub_01hv8y5ehszzq0yv20ttx3166y", "status": "active", "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j", "address_id": "add_01hv8y4jk511j9g2n9a2mexjbx", "business_id": null, "currency_code": "USD", "created_at": "2024-04-12T10:38:00.761Z", "updated_at": "2024-04-12T10:38:00.761Z", "started_at": "2024-04-12T10:37:59.556997Z", "first_billed_at": "2024-04-12T10:37:59.556997Z", "next_billed_at": "2024-05-12T10:37:59.556997Z", "paused_at": null, "canceled_at": null, "collection_mode": "automatic", "billing_details": null, "current_billing_period": { "starts_at": "2024-04-12T10:37:59.556997Z", "ends_at": "2024-05-12T10:37:59.556997Z" }, "billing_cycle": { "frequency": 1, "interval": "month" }, "scheduled_change": null, "items": [ { "status": "active", "quantity": 10, "recurring": true, "created_at": "2024-04-12T10:38:00.761Z", "updated_at": "2024-04-12T10:38:00.761Z", "previously_billed_at": "2024-04-12T10:37:59.556997Z", "next_billed_at": "2024-05-12T10:37:59.556997Z", "trial_dates": null, "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "type": "standard", "description": "Monthly", "name": "Monthly (per seat)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "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" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "AeroEdit Pro", "type": "standard", "tax_category": "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" } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2024-04-12T10:38:00.761Z", "updated_at": "2024-04-12T10:38:00.761Z", "previously_billed_at": "2024-04-12T10:37:59.556997Z", "next_billed_at": "2024-05-12T10:37:59.556997Z", "trial_dates": null, "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "type": "standard", "description": "Monthly", "name": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "10000", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "status": "active", "quantity": { "minimum": 1, "maximum": 100 }, "import_meta": null, "created_at": "2023-06-01T13:31:12.625056Z", "updated_at": "2024-04-09T07:23:00.907834Z" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Analytics addon", "type": "standard", "tax_category": "standard", "description": "Unlock advanced insights into your flight data with enhanced analytics and reporting features. Includes customizable reporting templates and trend analysis across flights.", "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png", "custom_data": null, "status": "active", "import_meta": null, "created_at": "2023-06-01T13:30:50.302Z", "updated_at": "2024-04-05T15:47:17.163Z" } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/cancel" }, "discount": null, "import_meta": null }, "meta": { "request_id": "e9ce8070-295a-4c8b-9180-7ab58dc31072" }}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.
Summary of changes
| Entity | Field | Change | Type |
|---|---|---|---|
| Subscription | subscription.items[].product | + Added | Field |