Bill for one-time charges

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 offer 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

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 a 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 want to bill them to.

You'll also need to get one-time prices that you want 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:

1. Build a request

   Create an items list that includes the one-time charges you want to bill for, then choose when to bill for them.

2. Preview one-time charge

   Preview charging for the one-time charge. This is optional, but recommended — you should present charge information to a customer.

3. Create one-time charge

   Send the request to create your one-time charge. Paddle creates a transaction now or in the future.

Build request

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.

1
2
3
4
5
6
7
8
9
1{
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.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "status": "active",
4    "customer_id": "ctm_01hw21d3hac6pe4wz04caz3kf4",
5    "address_id": "add_01hw2ac15twq7c162p05qzq8c9",
6    "business_id": null,
7    "currency_code": "USD",
8    "created_at": "2024-04-22T07:13:19.02Z",
9    "updated_at": "2024-04-22T08:24:45.138Z",
10    "started_at": "2024-04-22T07:13:18.412737Z",
11    "first_billed_at": "2024-04-22T07:13:18.412737Z",
12    "next_billed_at": "2025-04-22T07:13:18.412737Z",
13    "paused_at": null,
14    "canceled_at": null,
15    "collection_mode": "automatic",
16    "billing_details": null,
17    "current_billing_period": {
18      "starts_at": "2024-04-22T07:13:18.412737Z",
19      "ends_at": "2025-04-22T07:13:18.412737Z"
20    },

Create one-time charge

Send a POST request to the /subscriptions/{subscription_id}/charge endpoint.

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)

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_01hw2adtncz3kfj9tqhk3wcv3z",
4    "status": "active",
5    "customer_id": "ctm_01hw21d3hac6pe4wz04caz3kf4",
6    "address_id": "add_01hw2ac15twq7c162p05qzq8c9",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2024-04-22T07:13:19.02Z",
10    "updated_at": "2024-04-22T08:25:51.744Z",
11    "started_at": "2024-04-22T07:13:18.412737Z",
12    "first_billed_at": "2024-04-22T07:13:18.412737Z",
13    "next_billed_at": "2025-04-22T07:13:18.412737Z",
14    "paused_at": null,
15    "canceled_at": null,
16    "collection_mode": "automatic",
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2024-04-22T07:13:18.412737Z",
20      "ends_at": "2025-04-22T07:13:18.412737Z"

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:

• Billed next billing period

  When billed on the next_billing_period, get the subscription you billed the charge to using the API and include next_transaction.

• Billed immediately

  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.

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.

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
17    "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, which you may also filter for.

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 check transaction.line_items to get information about one-time charges.

Send a GET request to the /transactions endpoint.

Response

This example is a list of transactions, filtered by subscription and origin. There is one result for 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
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_charge",
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

Related pages