Paddle Billing
Search

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:

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:

  1. Build a request

    Create an items list that includes the one-time charges you'd like 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 your 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

Build an array of items, with an object containing either:

  • An item from your catalog

    Include a price ID and quantity for each item.

  • A non-catalog item

    Include a price object and quantity for each item.

Non-catalog items are one-off or bespoke items that are specific to that transaction. See: Bill for non-catalog items

You don't need to include existing recurring items on the subscription.

itemsarray[object]

List of one-time charges to bill for. Only prices where the billing_cycle is null may be added.

quantityinteger

Quantity to bill for.

price_idstring

Paddle ID of an an existing catalog price to bill for.

Along with your items array, include effective_from to tell Paddle when to bill for any one-time charges.

effective_fromstring

When one-time charges should be billed.

When billing one-time charges to automatically-collected subscriptions where the effective_from is immediately, Paddle tries to collect for the amount due right away.

You can optionally include on_payment_failure to tell Paddle how to handle payment failure when billing for a one-time charge.

If omitted, this defaults to prevent_change meaning that Paddle returns an error and doesn't bill for a one-time charge.

on_payment_failurestring

How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to prevent_change.

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.

Preview charge

Send a POST request to the /subscriptions/{subscription_id}/charge/preview endpoint with the request you built.

POSThttps://api.paddle.com/subscriptions/{subscription_id}/charge/preview
subscription_idstring

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

Create one-time charge

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

POSThttps://api.paddle.com/subscriptions/{subscription_id}/charge
subscription_idstring

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)

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.

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.

Events

transaction.createdOccurs when a one-time charge is billed to a subscription immediately, and when a subscription renews.
subscription.updatedOccurs when a subscription renews. One-time charges billed to a subscription on the next billing period are included in the created transaction.

Related pages