Skip to main content
POST
/
subscriptions
/
{subscription_id}
/
charge
Create 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', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "data": {
    "id": "sub_01hv8y5ehszzq0yv20ttx3166y",
    "status": "active",
    "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j",
    "address_id": "add_01hv8y4jk511j9g2n9a2mexjbx",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2024-04-12T10:38:00.761Z",
    "updated_at": "2024-04-12T10:56:12.174Z",
    "started_at": "2024-04-12T10:37:59.556997Z",
    "first_billed_at": "2024-04-12T10:37:59.556997Z",
    "next_billed_at": "2024-05-12T10:37:59.556997Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2024-04-12T10:37:59.556997Z",
      "ends_at": "2024-05-12T10:37:59.556997Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 20,
        "recurring": true,
        "created_at": "2024-04-12T10:38:00.761Z",
        "updated_at": "2024-04-12T10:49:38.76Z",
        "previously_billed_at": "2024-04-12T10:37:59.556997Z",
        "next_billed_at": "2024-05-12T10:37:59.556997Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 999
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:55:22.538367Z",
          "updated_at": "2024-04-11T13:54:52.254748Z"
        },
        "product": {
          "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "name": "AeroEdit Pro",
          "type": "standard",
          "tax_category": "standard",
          "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png",
          "custom_data": {
            "features": {
              "aircraft_performance": true,
              "compliance_monitoring": true,
              "flight_log_management": true,
              "payment_by_invoice": false,
              "route_planning": true,
              "sso": false
            },
            "suggested_addons": [
              "pro_01h1vjes1y163xfj1rh1tkfb65",
              "pro_01gsz97mq9pa4fkyy0wqenepkz"
            ],
            "upgrade_description": "Move from Basic to Pro to take advantage of aircraft performance, advanced route planning, and compliance monitoring."
          },
          "status": "active",
          "import_meta": null,
          "created_at": "2023-02-23T12:43:46.605Z",
          "updated_at": "2024-04-05T15:53:44.687Z"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-04-12T10:38:00.761Z",
        "updated_at": "2024-04-12T10:38:00.761Z",
        "previously_billed_at": "2024-04-12T10:37:59.556997Z",
        "next_billed_at": "2024-05-12T10:37:59.556997Z",
        "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-09T07:23:00.907834Z"
        },
        "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"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-04-12T10:49:38.765Z",
        "updated_at": "2024-04-12T10:49:38.765Z",
        "previously_billed_at": "2024-04-12T10:49:38.765Z",
        "next_billed_at": "2024-05-12T10:37:59.556997Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz95g2zrkagg294kpstx54r",
          "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "type": "standard",
          "description": "Monthly (recurring addon)",
          "name": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "25000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:59:52.159927Z",
          "updated_at": "2024-04-09T07:27:48.018296Z"
        },
        "product": {
          "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "name": "VIP support",
          "type": "standard",
          "tax_category": "standard",
          "description": "Get exclusive access to our expert team of product specialists, available to help you make the most of your AeroEdit subscription.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/qgyipKJwRtq98YNboipo_vip-support.png",
          "custom_data": null,
          "status": "active",
          "import_meta": null,
          "created_at": "2023-02-23T13:58:17.615Z",
          "updated_at": "2024-04-05T15:44:02.893Z"
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/cancel"
    },
    "discount": null,
    "import_meta": null
  },
  "meta": {
    "request_id": "53283483-dbd9-4987-9aa1-94656326dc58"
  }
}

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
Subscription · object
required

Represents a subscription entity.

​
meta
Meta · object
required

Information about this response.