# POST /subscriptions/{subscription_id}/charge **Create a one-time charge for a subscription** Creates a new one-time charge for a subscription. Use to bill non-recurring items to a subscription. Non-recurring items are price entities where the `billing_cycle` is `null`. If successful, Paddle responds with the updated subscription entity. However, one-time charges aren't held against the subscription entity, so the charges billed aren't returned in the response. Once created, to get details of a one-time charge: * When created with `effective_from` as `next_billing_period`, get the subscription the charge was billed to and use the `include` query parameter with the `next_transaction` value. * When created with `effective_from` as `immediately`, list transactions and use the `subscription_id` query parameter with the subscription ID of the subscription the charge was billed to. When an update results in an immediate charge, responses may take longer than usual while a payment attempt is processed. **Required permissions:** `subscription.write` ## Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `subscription_id` | string | required | Paddle ID of the subscription entity to work with. | ## Request body - `effective_from`: string (required) — When one-time charges should be billed. - `items`: array (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. (Items: 1–100) - `on_payment_failure`: string — 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 example ```json { "effective_from": "immediately", "items": [ { "price_id": "pri_01gsz98e27ak2tyhexptwc58yk", "quantity": 1 } ] } ``` ## Response (201) - `data`: object (required) — Represents a subscription entity. - `id`: string (required) — Unique Paddle ID for this subscription entity, prefixed with `sub_`. (pattern: `^sub_[a-z\d]{26}$`) - `status`: string (required) — Status of this subscription. Set automatically by Paddle. Use the pause subscription or cancel subscription operations to change. - `customer_id`: string (required) — Paddle ID of the customer that this subscription is for, prefixed with `ctm_`. (pattern: `^ctm_[a-z\d]{26}$`) - `address_id`: string (required) — Paddle ID of the address that this subscription is for, prefixed with `add_`. (pattern: `^add_[a-z\d]{26}$`) - `business_id` (required) — Paddle ID of the business that this subscription is for, prefixed with `biz_`. - `currency_code`: string (required) — 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_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `started_at` (required) — 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_at` (required) — 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_at` (required) — RFC 3339 datetime string of when this subscription is next scheduled to be billed. - `paused_at` (required) — 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_at` (required) — 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. - `discount` (required) — Details of the discount applied to this subscription. - `collection_mode`: string (required) — How payment is collected for transactions created for this subscription. `automatic` for checkout, `manual` for invoices. - `billing_details` (required) — Details for invoicing. Required if `collection_mode` is `manual`. - `current_billing_period` (required) — Current billing period for this subscription. Set automatically by Paddle based on the billing cycle. `null` for `paused` and `canceled` subscriptions. - `billing_cycle`: object (required) — How often this subscription renews. Set automatically by Paddle based on the prices on this subscription. - `interval`: string (required) — Unit of time. - `frequency`: integer (required) — Amount of time. (Min: 1) - `scheduled_change` (required) — 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_urls`: object (required) — 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. - `update_payment_method` (required) — Link to the page for this subscription in the customer portal with the payment method update form pre-opened. Use as part of workflows to let customers update their payment details. `null` for manually-collected subscriptions. - `cancel`: string (uri) (required) — Link to the page for this subscription in the customer portal with the subscription cancellation form pre-opened. Use as part of cancel subscription workflows. - `items`: array (required) — List of items on this subscription. Only recurring items are returned. (Items: 1–100) - `custom_data` (required) — Your own structured key-value data. - `import_meta` (required) — Import information for this entity. `null` if this entity is not imported. - `consent_requirements`: array (required) — List of active consent requirements for the subscription's current billing period. - `meta`: object (required) — Information about this response. - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request. ### Response example ```json { "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, "consent_requirements": [] }, "meta": { "request_id": "53283483-dbd9-4987-9aa1-94656326dc58" } } ```