Preview a one-time charge for a subscription

Permission required

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

Previews creating a one-time charge for a subscription without billing that charge. Typically used for previewing calculations before making changes to a subscription.

One-time charges are non-recurring items. These are price entities where the billing_cycle is null.

If successful, your response includes immediate_transaction, next_transaction, and recurring_transaction_details so you can see expected transactions for the changes.

Path Parameters

subscription_idstringrequired

Paddle ID of the subscription entity to work with.

Request Body

effective_fromstringrequired

When one-time charges should be billed.

itemsarray[object]required

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

You can charge for items that you've added to your catalog by passing the Paddle ID of an existing price entity, or you can charge for non-catalog items by passing a price object.

Non-catalog items can be for existing products, or you can pass a product object as part of your price to charge for a non-catalog product.

One of:

Catalog itemNon-catalog price for an existing productNon-catalog price and product

price_idstringrequired

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

quantityintegerrequired

Quantity to bill for.

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.

Response

dataobject

Represents a subscription preview when previewing a subscription.

statusstring

Status of this subscription. Set automatically by Paddle. Use the pause subscription or cancel subscription operations to change.

customer_idstring

Paddle ID of the customer that this subscription is for, prefixed with ctm_.

address_idstring

Paddle ID of the address that this subscription is for, prefixed with add_.

business_idstring or null

Paddle ID of the business that this subscription is for, prefixed with biz_.

currency_codestring

Supported three-letter ISO 4217 currency code. Transactions for this subscription are created in this currency. Must be USD, EUR, or GBP if collection_mode is manual.

created_atstring<date-time>

RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.

updated_atstring<date-time>

RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.

started_atstring<date-time> or null

RFC 3339 datetime string of when this subscription started. This may be different from first_billed_at if the subscription started in trial.

first_billed_atstring<date-time> or null

RFC 3339 datetime string of when this subscription was first billed. This may be different from started_at if the subscription started in trial.

next_billed_atstring<date-time> or null

RFC 3339 datetime string of when this subscription is next scheduled to be billed.

paused_atstring<date-time> or null

RFC 3339 datetime string of when this subscription was paused. Set automatically by Paddle when the pause subscription operation is used. null if not paused.

canceled_atstring<date-time> or null

RFC 3339 datetime string of when this subscription was canceled. Set automatically by Paddle when the cancel subscription operation is used. null if not canceled.

discountobject or null

Details of the discount applied to this subscription.

collection_modestring

How payment is collected for transactions created for this subscription. automatic for checkout, manual for invoices.

billing_detailsobject or null

Details for invoicing. Required if collection_mode is manual.

current_billing_periodobject or null

Current billing period for this subscription. Set automatically by Paddle based on the billing cycle. null for paused and canceled subscriptions.

billing_cycleobject

How often this subscription renews. Set automatically by Paddle based on the prices on this subscription.

scheduled_changeobject or null

Change that's scheduled to be applied to a subscription. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes. null if no scheduled changes.

management_urlsobject

Customer portal deep links for this subscription.

Authenticated links are only returned when your API key has Customer portal session (Write) permission. For security, the token appended to authenticated links is temporary. You shouldn't store them.

itemsarray[object]

List of items on this subscription. Only recurring items are returned.

custom_dataobject or null

Your own structured key-value data.

immediate_transactionobject or null

Preview of the immediate transaction created as a result of changes to the subscription. Returns a complete object where proration_billing_mode is prorated_immediately or full_immediately; null otherwise.

next_transactionobject or null

Preview of the next transaction for this subscription. Includes charges created where proration_billing_mode is prorated_next_billing_period or full_next_billing_period, as well as one-time charges. null if the subscription is scheduled to cancel or pause.

recurring_transaction_detailsobject

Preview of the recurring transaction for this subscription. This is what the customer can expect to be billed when there are no prorated or one-time charges.

update_summaryobject or null

Impact of this subscription change. Includes whether the change results in a charge or credit, and totals for prorated amounts.

import_metaobject or null

Import information for this entity. null if this entity is not imported.

metaobject

Information about this response.

request_idstring

Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

Request

1
2
3
4
5
6
7
8
9
1{
2  "effective_from": "immediately",
3  "items": [
4    {
5      "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
6      "quantity": 1
7    }
8  ]
9}

Response