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
Example
This example bills a one-time charge for a non-catalog price for an existing product to a subscription.
Create one-time charge
POST
/subscriptions/{subscription_id}/charge { "effective_from": "immediately", "items": [ { "price": { "product_id": "pro_01he5kwnnvgdv2chtpgavk2rf8", "description": "Loyalty offer 102", "name": "FLASH SALE Invigaron berries and seasonal skin", "unit_price": { "amount": "999", "currency_code": "USD" } }, "quantity": 1 } ]}Get related transaction
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.
GET
/transactions?subscription_id={subscription_id}&origin=subscription_charge { "data": [ { "id": "txn_01hj1992dn648813dfkw1kbt1x", "status": "completed", "customer_id": "ctm_01hh4fvwy9m5dz7s1qmxxk41b1", "address_id": "add_01hh4fvwyw5qj261rmjc32htx9", "business_id": null, "custom_data": null, "origin": "subscription_charge", "collection_mode": "automatic", "subscription_id": "sub_01hh4fwjc5w9hjrpf9mvechv5e", "invoice_id": "inv_01hj0y5zxygmr242ahsrcx9bmb", "invoice_number": "325-10333", "billing_details": null, "billing_period": { "starts_at": "2023-12-08T10:34:32.806947Z", "ends_at": "2024-01-08T10:34:32.806947Z" }, "currency_code": "USD", "discount_id": null, "created_at": "2023-12-19T14:57:02.268791Z", "updated_at": "2023-12-19T14:57:05.783723Z", "billed_at": "2023-12-19T14:57:01.877466Z", "items": [ { "price": { "id": "pri_01hj19929zp9h998zz1anjm8bq", "description": "Loyalty offer 102", "name": "FLASH SALE Invigaron berries and seasonal skin", "product_id": "pro_01he5kwnnvgdv2chtpgavk2rf8", "billing_cycle": null, "trial_period": null, "tax_mode": "account_setting", "unit_price": { "amount": "999", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "quantity": { "minimum": 1, "maximum": 100 }, "status": "active" }, "quantity": 1 } ], "details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "999", "discount": "0", "tax": "89", "total": "1088" } } ], "totals": { "subtotal": "999", "tax": "89", "discount": "0", "total": "1088", "grand_total": "1088", "fee": "104", "credit": "0", "credit_to_balance": "0", "balance": "0", "earnings": "895", "currency_code": "USD" }, "adjusted_totals": { "subtotal": "999", "tax": "89", "total": "1088", "grand_total": "1088", "fee": "104", "earnings": "895", "currency_code": "USD" }, "payout_totals": { "subtotal": "999", "tax": "89", "discount": "0", "total": "1088", "credit": "0", "credit_to_balance": "0", "balance": "0", "grand_total": "1088", "fee": "104", "earnings": "895", "currency_code": "USD" }, "adjusted_payout_totals": { "subtotal": "999", "tax": "89", "total": "1088", "fee": "104", "chargeback_fee": { "amount": "0", "original": null }, "earnings": "895", "currency_code": "USD" }, "line_items": [ { "id": "txnitm_01hj1992sf3a3x5h5brk6p7xx3", "price_id": "pri_01hj19929zp9h998zz1anjm8bq", "quantity": 1, "totals": { "subtotal": "999", "tax": "89", "discount": "0", "total": "1088" }, "product": { "id": "pro_01he5kwnnvgdv2chtpgavk2rf8", "name": "Invigaron berries pack", "description": null, "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/XBWZPsQoSc6YyViK5ocI_fire.png", "custom_data": null, "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "999", "tax": "89", "discount": "0", "total": "1088" } } ] }, "payments": [ { "payment_attempt_id": "b840a174-d28d-4d75-916b-f8c12a748588", "stored_payment_method_id": "d509416d-f8ec-4558-bfbc-7e2184bd6d8a", "amount": "1088", "status": "captured", "error_code": null, "method_details": { "type": "card", "card": { "type": "visa", "last4": "4242", "expiry_month": 1, "expiry_year": 2025, "cardholder_name": "Michael McGovern" } }, "created_at": "2023-12-19T14:57:02.358501Z", "captured_at": "2023-12-19T14:57:03.652376Z" } ], "checkout": { "url": "https://aeroedit.com/pay?_ptxn=txn_01hj1992dn648813dfkw1kbt1x" } } ], "meta": { "request_id": "4ad70ade-89c1-4431-9c6f-901d6ccb9897", "pagination": { "per_page": 30, "next": "https://api.paddle.com/transactions?after=txn_01hj1992dn648813dfkw1kbt1x&origin=subscription_charge&subscription_id=sub_01hh4fwjc5w9hjrpf9mvechv5e", "has_more": false, "estimated_total": 1 } }}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.
Summary of changes
| Entity | Field | Change | Type |
|---|---|---|---|
| subscription | items[].price_id | ~ Updated | Field |
| This field is no longer required if you include a price object instead. | |||
| subscription | items[].price | + Added | Field |
| You can send a price object instead of a price_id to bill for a non-catalog item. | |||