# POST /subscriptions/{subscription_id}/charge/preview

**Preview a one-time charge for a subscription**

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.

**Required permissions:** `subscription.read`

## 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 (200)

- `data`: object (required) — Represents a subscription preview when previewing a subscription.
  - `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.
  - `immediate_transaction` (required) — 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_transaction` (required) — 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_details`: object (required) — 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.
    - `tax_rates_used`: array (required) — List of tax rates applied to this transaction preview.
    - `totals`: object (required) — Breakdown of the total for a transaction preview. `fee` and `earnings` always return `null` for transaction previews.
      - `subtotal`: string (required) — Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
      - `discount`: string (required) — Total discount as a result of any discounts applied.

Except for percentage discounts, Paddle applies tax to discounts based on the line item `price.tax_mode`. If `price.tax_mode` for a line item is `internal`, Paddle removes tax from the discount applied.
      - `tax`: string (required) — Total tax on the subtotal.
      - `total`: string (required) — Total after discount and tax.
      - `credit`: string (required) — Total credit applied to this transaction. This includes credits applied using a customer's credit balance and adjustments to a `billed` transaction.
      - `credit_to_balance`: string (required) — Additional credit generated from negative `details.line_items`. This credit is added to the customer balance.
      - `balance`: string (required) — Total due on a transaction after credits and any payments.
      - `grand_total`: string (required) — Total due on a transaction after credits but before any payments.
      - `grand_total_tax`: string (required) — Net tax amount included in `grand_total`. Equals the full `tax` amount unless credits are applied, in which case this value is proportionally reduced.
      - `fee` (required) — Total fee taken by Paddle for this transaction. `null` until the transaction is `completed` and the fee is processed.
      - `earnings` (required) — Total earnings for this transaction. This is the total minus the Paddle fee. `null` until the transaction is `completed` and the fee is processed.
      - `currency_code`: string (required) — Three-letter ISO 4217 currency code of the currency used for this transaction.
    - `line_items`: array (required) — Information about line items for this transaction preview. Different from transaction preview `items` as they include totals calculated by Paddle. Considered the source of truth for line item totals.
  - `update_summary` (required)
  - `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": {
    "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",
        "grand_total_tax": "1331",
        "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",
          "grand_total_tax": "1331",
          "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",
          "grand_total_tax": "1766",
          "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"
            },
            "proration": null
          }
        ]
      },
      "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"
        },
        "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": null,
          "status": "active",
          "import_meta": null,
          "created_at": "2023-02-23T12:43:09.062Z",
          "updated_at": "2024-04-05T15:56:39.477Z"
        }
      },
      {
        "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"
        },
        "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.",
          "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"
        }
      }
    ],
    "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,
    "consent_requirements": []
  },
  "meta": {
    "request_id": "03130bfb-77f3-4fa9-b5a6-b31b06139377"
  }
}
```