Add recurring non-catalog products and prices to a subscription

Add recurring items to a subscription without having to add them to your product catalog by passing price or product attributes when updating a subscription.

What's new?

We updated the Paddle platform so that now you can add recurring items that aren't in your catalog when updating subscriptions.

Recently, we updated the Paddle platform so that you can create transactions for products and prices that aren't in your catalog. We followed that up with an update that lets you bill non-catalog one-time charges to a subscription.

With this update, you can pass price and product attributes directly when updating subscriptions, too. This means that you can work with both recurring and one-time non-catalog items on subscriptions.

Adding non-catalog items to a subscription is great for one-off or bespoke items that are specific to that subscription. They let you manage your product catalog outside of Paddle.

Summary of changes to fields

Request bodies

This is a summary of the changes to fields in the Paddle API in request bodies when working with the preview an update for a subscription and the update a subscription operations:

Field	Change	Notes
`subscription.items[].price_id`	Validation change	This field is no longer required if you include a `price` object instead.
`subscription.items[].price`	New field	You can send a price object instead of a `price_id` to bill for a non-catalog item.

Example

Request

This example adds a new item for a non-catalog price for an existing product to a subscription, along with two catalog items that already existed on the subscription.

It includes prorated_immediately as the billing mode, meaning Paddle calculates a prorated charge for the new items and bills for it right away.

PATCHhttps://api.paddle.com/subscriptions/{subscription_id}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "items": [
3    {
4      "quantity": 1,
5      "price": {
6        "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
7        "description": "VIP support",
8        "name": "VIP support with monthly specialist data export",
9        "billing_cycle": {
10          "interval": "month",
11          "frequency": 1
12        },
13        "unit_price": {
14          "amount": "10000",
15          "currency_code": "USD"
16        }
17      }
18    },
19    {
20      "quantity": 10,

Response

If successful, Paddle returns a copy of the updated subscription entity.

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_01j48ynsppxshcen117ewqe8xy",
4    "status": "active",
5    "customer_id": "ctm_01j48yn43190mxmde4r6necxqn",
6    "address_id": "add_01j48yn43gz7cbvjabnf1dpf8h",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2024-08-02T07:08:12.886Z",
10    "updated_at": "2024-08-02T07:22:41.449Z",
11    "started_at": "2024-08-02T07:08:12.117331Z",
12    "first_billed_at": "2024-08-02T07:08:12.117331Z",
13    "next_billed_at": "2024-09-02T07:08:12.117331Z",
14    "paused_at": null,
15    "canceled_at": null,
16    "collection_mode": "automatic",
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2024-08-02T07:08:12.117331Z",
20      "ends_at": "2024-09-02T07:08:12.117331Z"

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 update a subscription using the API to start charging for non-catalog items.

Learn more

Bill for non-catalog items

Add or remove items on a subscription

Sign up to get notified when our API evolves