Bill for one-time charges
Bill one-time charges to a subscription to charge for one-off things, like setup or onboarding fees or support incident charges. Charge immediately, or add them to the next renewal.
As well as adding recurring items to subscriptions, Paddle lets you bill for one-time charges. One-time charges are sometimes called "one-off," "ad-hoc," or "non-recurring" charges or fees.
Bill one-time charges to a subscription when:
- You charge customers a fee at the start of their subscription for things like setup, implementation, deployment, or activation
- You offer services to subscribed customers, like auditing, data export, data migration, or incident support
- You sell passes to access modules or features, like a 10-day pro pass for customers on a starter plan
- You want to provide an easy way for customers to buy ebooks, access to webinars, or other resources you offer
You can't make changes to a subscription if the next billing period is within 30 minutes.
How it works
One-time charges for a subscription are items that don't recur. The billing_cycle
against the related price entity is null
.
They're typically charged at the start of a subscription, like setup fees, or mid-cycle for things like incident support or data auditing. You can also use them to sell additional products, like ebooks, access to webinars, or other educational resources.
While you could create an entirely new transaction for additional products, billing them to the subscription lets you:
Automatically-collect using the payment method on file for the subscription
No need to ask your customer for card details again. Use the billing details that you use to collect for subscription payments.
Add one-time charges to the next renewal
Collect for your one-time charges when you next collect for a subscription, offering an integrated experience.
As they're non-recurring, one-time charges aren't added to the items
list against subscriptions. This list is just for recurring items.
Proration doesn't apply to one-time charges because they're not related to the billing period. Customers are always charged the full amount.
Related subscription changes
Billing for one-time charges is typically used when you want to charge customers for one-off fees or ad-hoc products.
Depending on what you're looking to do, you might also like to:
Add items to charge for new users, modules, or other recurring addons
Adding or removing users, modules, one-off fees, or other addons typically involves adding or removing items. For example, you might offer a module called "Advanced Reporting" that customers can subscribe to.
Replace items to upgrade or downgrade a subscription
Upgrading or downgrading a subscription plan typically involves replacing products. For example, you might replace a "Starter plan" product with a "Premium plan" product to upgrade.
Before you begin
To bill one-time charges to a subscription, you'll need to get the subscription ID for the subscription you'd like to bill them to.
You'll also need to get one-time prices that you'd like to bill for. One-time charges are prices where the billing_cycle
is null
. Use the recurring
query parameter with the value false
when listing prices with the API to return one-time prices.
Bill for one-time charges
Bill one-time charges to a subscription in three steps:
Create an
items
list that includes the one-time charges you'd like to bill for, then choose when to bill for them.Preview charging for the one-time charge. This is optional, but recommended — you should present charge information to your customer.
Send the request to create your one-time charge. Paddle creates a transaction now or in the future.
Build request
Build a request that includes an items
array. Your array should include an object for each one-time charge you'd like to add, where each object contains a price ID and a quantity.
You don't need to include existing recurring items on the subscription.
List of one-time charges to add to this subscription. Only prices where the billing_cycle
is null
may be added.
Paddle ID for the price to add to this subscription, prefixed with pri_
.
Quantity of this item to add to the subscription. If updating an existing item and not changing the quantity, you may omit quantity
.
Along with your items
array, include effective_from
to tell Paddle when to bill for any one-time charges.
When one-time charges should be billed.
Request
This example bills for a one-time charge on the next billing period. This means Paddle adds the charge to the transaction created when the subscription next renews.
1234567891{
2 "effective_from": "next_billing_period",
3 "items": [
4 {
5 "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
6 "quantity": 1
7 }
8 ]
9}
Preview charge
Send a POST
request to the /subscriptions/{subscription_id}/charge/preview
endpoint with the request you built.
Paddle ID of the subscription entity to work with.
Response
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.
Previews include immediate_transaction
, next_transaction
, and recurring_transaction_details
that give you information about upcoming transactions impacted as a result of this change. In this example, effective_from
is next_billing_period
, meaning:
Paddle doesn't create a charge immediately, so immediate_transaction
is null
Paddle charges for this item on the next billing period, so it's included in next_transaction
12345678910111213141516171819201{
2 "data": {
3 "status": "active",
4 "customer_id": "ctm_01h8441jn5pcwrfhwh78jqt8hk",
5 "address_id": "add_01h848pep46enq8y372x7maj0p",
6 "business_id": "biz_01h84a7hr4pzhsajkm8tev89ev",
7 "currency_code": "USD",
8 "created_at": "2023-08-21T11:31:10.292Z",
9 "updated_at": "2023-08-23T13:46:53.92Z",
10 "started_at": "2023-08-21T11:31:08.689295Z",
11 "first_billed_at": "2023-08-21T11:31:08.689295Z",
12 "next_billed_at": "2023-09-21T11:31:08.689295Z",
13 "paused_at": null,
14 "canceled_at": null,
15 "collection_mode": "automatic",
16 "billing_details": null,
17 "current_billing_period": {
18 "starts_at": "2023-08-21T11:31:08.689295Z",
19 "ends_at": "2023-09-21T11:31:08.689295Z"
20 },
Create one-time charge
Send a POST
request to the /subscriptions/{subscription_id}/charge
endpoint.
Paddle ID of the subscription entity to work with.
Response
One-time charges aren't held against the subscription entity, so the charges you billed for aren't returned in the response.
If successful, Paddle returns a copy of the updated subscription entity.
The updated subscription entity doesn't include the item you just added. The items
array only includes recurring items.
You can query the API to get information about the one-time charge. See: Get a one-time charge (below)
12345678910111213141516171819201{
2 "data": {
3 "status": "active",
4 "customer_id": "ctm_01h8441jn5pcwrfhwh78jqt8hk",
5 "address_id": "add_01h848pep46enq8y372x7maj0p",
6 "business_id": "biz_01h84a7hr4pzhsajkm8tev89ev",
7 "currency_code": "USD",
8 "created_at": "2023-08-21T11:31:10.292Z",
9 "updated_at": "2023-08-23T13:46:53.92Z",
10 "started_at": "2023-08-21T11:31:08.689295Z",
11 "first_billed_at": "2023-08-21T11:31:08.689295Z",
12 "next_billed_at": "2023-09-21T11:31:08.689295Z",
13 "paused_at": null,
14 "canceled_at": null,
15 "collection_mode": "automatic",
16 "billing_details": null,
17 "current_billing_period": {
18 "starts_at": "2023-08-21T11:31:08.689295Z",
19 "ends_at": "2023-09-21T11:31:08.689295Z"
20 },
Get one-time charges
One-time charges aren't added to the subscription items
list. This array is only for recurring items.
To get details of a one-time charge:
When billed on the
next_billing_period
, get the subscription you billed the charge to using the API and includenext_transaction
.When billed
immediately
, list transactions using the API and filter to see transactions for the subscription you billed the charge to.
Next billing period
When you bill a one-time charge to a subscription with effective_from
as next_billing_period
, Paddle adds it to the next renewal transaction.
You can see the one-time charge by getting the subscription that you billed the charge to, using the include
query parameter to return the next_transaction
. One-time charges are detailed in next_transaction.details.line_items
, along with any recurring items.
Send a GET
request to the /subscriptions/{subscription_id}
endpoint.
Paddle ID of the subscription entity to work with.
Include related entities in the response.
Response
This example is a subscription entity with next_transaction
included. There's an object for "Custom domains" (pri_01gsz98e27ak2tyhexptwc58yk
), a one-time charge, in next_transaction.details.line_items
.
171819202122232425262728293031323334353617 "billing_details": null,
18 "current_billing_period": {
19 "starts_at": "2023-08-22T08:25:12.565118Z",
20 "ends_at": "2023-09-22T08:25:12.565118Z"
21 },
22 "billing_cycle": {
23 "frequency": 1,
24 "interval": "month"
25 },
26 "next_transaction": {
27 "billing_period": {
28 "starts_at": "2023-09-22T08:25:12.565118Z",
29 "ends_at": "2023-10-22T08:25:12.565118Z"
30 },
31 "details": {
32 "tax_rates_used": [
33 {
34 "tax_rate": "0.08875",
35 "totals": {
36 "subtotal": "119900",
Immediately
When you bill a one-time charge to a subscription with effective_from
as immediately
, Paddle creates a transaction for it right away.
You can see the one-time charge by listing transactions, filtering to see transactions for the subscription you billed the charge to. The origin
against the transaction is subscription_charge
.
If you've subscribed to notifications for transaction events,
transaction.created
occurs when you bill for one-time charges. The notification includes the complete transaction entity. You can checktransaction.line_items
to get information about one-time charges.
Send a GET
request to the /transactions
endpoint.
Return entities related to the specified subscription. Use a comma separated list to specify multiple subscription IDs.
Response
This example is a transaction entity created for "Custom domains" (pri_01gsz98e27ak2tyhexptwc58yk
), a one-time charge. The origin
for this transaction is subscription_charge
, indicating it was created because a one-time charge was billed to a subscription.
12345678910111213141516171819201{
2 "data": [
3 {
4 "id": "txn_01h3kvj0hs5e3q1d53g5jnfbg3",
5 "status": "completed",
6 "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
7 "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
8 "business_id": null,
9 "custom_data": null,
10 "origin": "subscription_update",
11 "collection_mode": "automatic",
12 "subscription_id": "sub_01h3h3a9sfpr5syq38tq0sd4sp",
13 "invoice_id": "inv_01h3kvj4zfm911d3p0qbtg5ksf",
14 "invoice_number": "325-10054",
15 "billing_details": null,
16 "billing_period": {
17 "starts_at": "2023-08-22T08:25:12.565118Z",
18 "ends_at": "2023-09-22T08:25:12.565118Z"
19 },
20 "currency_code": "USD",
Events
transaction.created | Occurs when a one-time charge is billed to a subscription immediately, and when a subscription renews. |
subscription.updated | Occurs when a subscription renews. One-time charges billed to a subscription on the next billing period are included in the created transaction. |