Bill one-time non-catalog items to a subscription
Bill a one-time item to a subscription without having to add it to your product catalog by passing price or product attributes.
What's new?
We updated the Paddle platform so that now you can bill one-time charges to a subscription for products and prices that aren't in your catalog.
In a future update, we'll release functionality to let you work with recurring non-catalog items on subscriptions, too. This change is scheduled for Q1 2024.
How it works
We recently updated the Paddle platform so that you can create transactions for products and prices that aren't in your catalog. This update lets you bill non-catalog one-time charges to a subscription, too.
When previewing or creating one-time charges for a subscription, you can now pass price and product attributes directly.
Billing one-time 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.
It works in the same way that non-catalog items work when creating or updating a transaction, meaning you can:
- Pass a price object for an existing product to charge for a custom price for a catalog product
- Pass a price object and a product object to charge for a custom price for a custom product
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 a one-time charge for a subscription and the create a one-time charge for 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
This example bills a one-time charge for a non-catalog price for an existing product to a subscription.
12345678910111213141516171{
2 "effective_from": "immediately",
3 "items": [
4 {
5 "price": {
6 "product_id": "pro_01he5kwnnvgdv2chtpgavk2rf8",
7 "description": "Loyalty offer 102",
8 "name": "FLASH SALE Invigaron berries and seasonal skin",
9 "unit_price": {
10 "amount": "999",
11 "currency_code": "USD"
12 }
13 },
14 "quantity": 1
15 }
16 ]
17}If successful, Paddle returns a preview of the updated subscription entity. The subscription entity doesn't include the item you just added. The items array only includes recurring items.
You can send a follow-up request to get the related transaction that Paddle created for this one-time charge.
Return entities related to the specified subscription. Use a comma-separated list to specify multiple subscription IDs.
Return entities related to the specified origin. Use a comma-separated list to specify multiple origins.
171819202122232425262728293031323334353617 "starts_at": "2023-12-08T10:34:32.806947Z",
18 "ends_at": "2024-01-08T10:34:32.806947Z"
19 },
20 "currency_code": "USD",
21 "discount_id": null,
22 "created_at": "2023-12-19T14:57:02.268791Z",
23 "updated_at": "2023-12-19T14:57:05.783723Z",
24 "billed_at": "2023-12-19T14:57:01.877466Z",
25 "items": [
26 {
27 "price": {
28 "id": "pri_01hj19929zp9h998zz1anjm8bq",
29 "description": "Loyalty offer 102",
30 "name": "FLASH SALE Invigaron berries and seasonal skin",
31 "product_id": "pro_01he5kwnnvgdv2chtpgavk2rf8",
32 "billing_cycle": null,
33 "trial_period": null,
34 "tax_mode": "account_setting",
35 "unit_price": {
36 "amount": "999",
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 bill one-time charges to a subscription using the API to start charging for non-catalog items.
This is part of a set of changes around non-catalog items. In a future update, we'll release functionality to let you work with recurring non-catalog items on subscriptions, too. This change is scheduled for Q1 2024.
