Skip to main content
POST
/
subscriptions
/
{subscription_id}
/
charge
/
preview
Preview a one-time charge for a subscription
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    effective_from: 'immediately',
    items: [{price_id: 'pri_01gsz98e27ak2tyhexptwc58yk', quantity: 1}]
  })
};

fetch('https://api.paddle.com/subscriptions/{subscription_id}/charge/preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "data": {
    "status": "active",
    "customer_id": "ctm_01hrffh7gvp29kc7xahm8wddwa",
    "address_id": "add_01hxh60j19j6gj877cywv20g13",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2024-05-10T12:01:47.199Z",
    "updated_at": "2024-05-13T10:40:04.576Z",
    "started_at": "2024-05-10T12:01:46.293348Z",
    "first_billed_at": "2024-05-10T12:01:46.293348Z",
    "next_billed_at": "2024-06-10T12:01:46.293348Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2024-05-10T12:01:46.293348Z",
      "ends_at": "2024-06-10T12:01:46.293348Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "recurring_transaction_details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "15000",
            "discount": "0",
            "tax": "1331",
            "total": "16331"
          }
        }
      ],
      "totals": {
        "subtotal": "15000",
        "tax": "1331",
        "discount": "0",
        "total": "16331",
        "fee": null,
        "credit": "0",
        "credit_to_balance": "0",
        "balance": "16331",
        "grand_total": "16331",
        "earnings": null,
        "currency_code": "USD"
      },
      "line_items": [
        {
          "price_id": "pri_01gsz8ntc6z7npqqp6j4ys0w1w",
          "quantity": 5,
          "totals": {
            "subtotal": "5000",
            "tax": "444",
            "discount": "0",
            "total": "5444"
          },
          "product": {
            "id": "pro_01gsz4s0w61y0pp88528f1wvvb",
            "name": "AeroEdit Basic",
            "type": "standard",
            "tax_category": "standard",
            "description": "Ideal for hobbyist pilots AeroEdit Basic offers flight log creation, editing, basic performance tracking, route planning, and export options.",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/oi0r8qNmQzuNpj9pLHcT_basic.png",
            "custom_data": {
              "features": {
                "aircraft_performance": false,
                "compliance_monitoring": false,
                "flight_log_management": true,
                "payment_by_invoice": false,
                "route_planning": false,
                "sso": false
              },
              "suggested_addons": [
                "pro_01h1vjes1y163xfj1rh1tkfb65",
                "pro_01gsz97mq9pa4fkyy0wqenepkz"
              ],
              "upgrade_description": null
            },
            "status": "active",
            "import_meta": null,
            "created_at": "2023-02-23T12:43:09.062Z",
            "updated_at": "2024-04-05T15:56:39.477Z"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "1000",
            "discount": "0",
            "tax": "89",
            "total": "1089"
          },
          "proration": {
            "rate": "1",
            "billing_period": {
              "starts_at": "2024-05-10T12:01:46.293348Z",
              "ends_at": "2024-06-10T12:01:46.293348Z"
            }
          }
        },
        {
          "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "quantity": 1,
          "totals": {
            "subtotal": "10000",
            "tax": "887",
            "discount": "0",
            "total": "10887"
          },
          "product": {
            "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
            "name": "Analytics addon",
            "type": "standard",
            "tax_category": "standard",
            "description": "Unlock advanced insights into your flight data with enhanced analytics and reporting features. Includes customizable reporting templates and trend analysis across flights.",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png",
            "custom_data": null,
            "status": "active",
            "import_meta": null,
            "created_at": "2023-06-01T13:30:50.302Z",
            "updated_at": "2024-04-05T15:47:17.163Z"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "10000",
            "discount": "0",
            "tax": "887",
            "total": "10887"
          },
          "proration": {
            "rate": "1",
            "billing_period": {
              "starts_at": "2024-05-10T12:01:46.293348Z",
              "ends_at": "2024-06-10T12:01:46.293348Z"
            }
          }
        }
      ]
    },
    "next_transaction": {
      "billing_period": {
        "starts_at": "2024-06-10T12:01:46.293348Z",
        "ends_at": "2024-07-10T12:01:46.293348Z"
      },
      "details": {
        "tax_rates_used": [
          {
            "tax_rate": "0.08875",
            "totals": {
              "subtotal": "15000",
              "discount": "0",
              "tax": "1331",
              "total": "16331"
            }
          }
        ],
        "totals": {
          "subtotal": "15000",
          "tax": "1331",
          "discount": "0",
          "total": "16331",
          "fee": null,
          "credit": "0",
          "credit_to_balance": "0",
          "balance": "16331",
          "grand_total": "16331",
          "earnings": null,
          "currency_code": "USD"
        },
        "line_items": [
          {
            "price_id": "pri_01gsz8ntc6z7npqqp6j4ys0w1w",
            "quantity": 5,
            "totals": {
              "subtotal": "5000",
              "tax": "444",
              "discount": "0",
              "total": "5444"
            },
            "product": {
              "id": "pro_01gsz4s0w61y0pp88528f1wvvb",
              "name": "AeroEdit Basic",
              "type": "standard",
              "tax_category": "standard",
              "description": "Ideal for hobbyist pilots AeroEdit Basic offers flight log creation, editing, basic performance tracking, route planning, and export options.",
              "image_url": "https://paddle.s3.amazonaws.com/user/165798/oi0r8qNmQzuNpj9pLHcT_basic.png",
              "custom_data": {
                "features": {
                  "aircraft_performance": false,
                  "compliance_monitoring": false,
                  "flight_log_management": true,
                  "payment_by_invoice": false,
                  "route_planning": false,
                  "sso": false
                },
                "suggested_addons": [
                  "pro_01h1vjes1y163xfj1rh1tkfb65",
                  "pro_01gsz97mq9pa4fkyy0wqenepkz"
                ],
                "upgrade_description": null
              },
              "status": "active",
              "import_meta": null,
              "created_at": "2023-02-23T12:43:09.062Z",
              "updated_at": "2024-04-05T15:56:39.477Z"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "1000",
              "discount": "0",
              "tax": "89",
              "total": "1089"
            },
            "proration": {
              "rate": "1",
              "billing_period": {
                "starts_at": "2024-06-10T12:01:46.293348Z",
                "ends_at": "2024-07-10T12:01:46.293348Z"
              }
            }
          },
          {
            "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
            "quantity": 1,
            "totals": {
              "subtotal": "10000",
              "tax": "887",
              "discount": "0",
              "total": "10887"
            },
            "product": {
              "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
              "name": "Analytics addon",
              "type": "standard",
              "tax_category": "standard",
              "description": "Unlock advanced insights into your flight data with enhanced analytics and reporting features. Includes customizable reporting templates and trend analysis across flights.",
              "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png",
              "custom_data": null,
              "status": "active",
              "import_meta": null,
              "created_at": "2023-06-01T13:30:50.302Z",
              "updated_at": "2024-04-05T15:47:17.163Z"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "10000",
              "discount": "0",
              "tax": "887",
              "total": "10887"
            },
            "proration": {
              "rate": "1",
              "billing_period": {
                "starts_at": "2024-06-10T12:01:46.293348Z",
                "ends_at": "2024-07-10T12:01:46.293348Z"
              }
            }
          }
        ]
      },
      "adjustments": []
    },
    "immediate_transaction": {
      "billing_period": {
        "starts_at": "2024-05-13T10:40:05.929Z",
        "ends_at": "2024-06-10T12:01:46.293348Z"
      },
      "details": {
        "tax_rates_used": [
          {
            "tax_rate": "0.08875",
            "totals": {
              "subtotal": "19900",
              "discount": "0",
              "tax": "1766",
              "total": "21666"
            }
          }
        ],
        "totals": {
          "subtotal": "19900",
          "tax": "1766",
          "discount": "0",
          "total": "21666",
          "fee": null,
          "credit": "0",
          "credit_to_balance": "0",
          "balance": "21666",
          "grand_total": "21666",
          "earnings": null,
          "currency_code": "USD"
        },
        "line_items": [
          {
            "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
            "quantity": 1,
            "totals": {
              "subtotal": "19900",
              "tax": "1766",
              "discount": "0",
              "total": "21666"
            },
            "product": {
              "id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
              "name": "Custom domains",
              "type": "standard",
              "tax_category": "standard",
              "description": "Make AeroEdit truly your own with custom domains. Custom domains reinforce your brand identity and make it easy for your team to access your account.",
              "image_url": "https://paddle.s3.amazonaws.com/user/165798/XIG7UXoJQHmlIAiKcnkA_custom-domains.png",
              "custom_data": null,
              "status": "active",
              "import_meta": null,
              "created_at": "2023-02-23T14:01:02.441Z",
              "updated_at": "2024-04-05T15:43:28.971Z"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "19900",
              "discount": "0",
              "tax": "1766",
              "total": "21666"
            }
          }
        ]
      },
      "adjustments": []
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 5,
        "recurring": true,
        "created_at": "2024-05-10T12:01:47.199Z",
        "updated_at": "2024-05-10T12:01:47.199Z",
        "previously_billed_at": "2024-05-10T12:01:46.293348Z",
        "next_billed_at": "2024-06-10T12:01:46.293348Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz8ntc6z7npqqp6j4ys0w1w",
          "product_id": "pro_01gsz4s0w61y0pp88528f1wvvb",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "1000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:51:18.406674Z",
          "updated_at": "2024-04-05T14:29:40.000454Z"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-05-10T12:01:47.199Z",
        "updated_at": "2024-05-10T12:01:47.199Z",
        "previously_billed_at": "2024-05-10T12:01:46.293348Z",
        "next_billed_at": "2024-06-10T12:01:46.293348Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "import_meta": null,
          "created_at": "2023-06-01T13:31:12.625056Z",
          "updated_at": "2024-04-12T10:42:45.476453Z"
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hxh62z5zb2jeebtnrjfkk15b/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hxh62z5zb2jeebtnrjfkk15b/cancel"
    },
    "discount": null,
    "update_summary": {
      "credit": {
        "amount": "0",
        "currency_code": "USD"
      },
      "charge": {
        "amount": "21666",
        "currency_code": "USD"
      },
      "result": {
        "action": "charge",
        "amount": "21666",
        "currency_code": "USD"
      }
    },
    "import_meta": null
  },
  "meta": {
    "request_id": "03130bfb-77f3-4fa9-b5a6-b31b06139377"
  }
}

Authorizations

​
Authorization
string
header
required

Requests are authenticated with API keys. Provide your API key as a Bearer token in the Authorization header.

API keys are assigned permissions, granting them access to entities and operations. Each endpoint may require one or more permissions, defined with the x-permissions extension. Values for include parameters may require specific permissions as defined in the x-enum-permissions extension. See all available permissions in the permission schema or documentation.

Get an API key and select the permissions you need from the Paddle dashboard under Paddle > Developer Tools > Authentication.

Path Parameters

​
subscription_id
string
required

Paddle ID of the subscription entity to work with.

Example:

"sub_01gvne45dvdhg5gdxrz6hh511r"

Body

application/json

Represents a one-time charge for a subscription.

​
effective_from
enum<string>
required

When one-time charges should be billed.

Available options:
next_billing_period,
immediately
​
items
(Catalog item · object | Non-catalog price for an existing product · object | Non-catalog price and product · 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.

Required array length: 1 - 100 elements

Add a catalog item to a subscription. In this case, the product and price that you're billing for exist in your product catalog in Paddle.

​
on_payment_failure
enum<string>
default:prevent_change

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

Available options:
prevent_change,
apply_change

Response

OK

​
data
SubscriptionPreview · object
required

Represents a subscription preview when previewing a subscription.

​
meta
Meta · object
required

Information about this response.