---
title: "Preview a Paddle Billing subscription transaction"
method: POST
path: "/billing/subscriptions/{subscription_id}/preview"
tags: ["Billing"]
---

# Preview a Paddle Billing subscription transaction

`POST /billing/subscriptions/{subscription_id}/preview`

Preview the cost and details of a Billing subscription before creation

## Path parameters

- `subscription_id` string, required

## Request body

- BillingSubscriptionUpdate — DTO for updating a Billing subscription with a single item
  - `items` BillingSubscriptionItem[], required
    - `price_id` string, required
    - `quantity` integer

## Response `200`

Successful Response

- BillingTransactionPreview — DTO for previewing a Billing transaction
  - `id` string, required
  - `status` 'active' | 'canceled' | 'past_due' | 'paused' | 'trialing', required — An enumeration.
  - `customer_id` string, required
  - `currency_code` string, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `started_at` string, date-time
  - `first_billed_at` string, date-time
  - `next_billed_at` string, date-time
  - `paused_at` string, date-time
  - `canceled_at` string, date-time
  - `collection_mode` string
  - `billing_details` object
  - `current_billing_period` BillingPeriod
    - `starts_at` string, date-time, required
    - `ends_at` string, date-time, required
  - `billing_cycle` Duration
    - `interval` string, required
    - `frequency` integer, required
  - `scheduled_change` object
  - `items` PaddleBillingSubscriptionItem[], required
    - `status` string, required
    - `quantity` integer, required
    - `price` PaddleBillingPrice, required
      - `id` string, required
      - `product_id` string, required
      - `name` string
      - `description` string
      - `type` string
      - `billing_cycle` Duration
        - `interval` string, required
        - `frequency` integer, required
      - `trial_period` Duration
        - `interval` string, required
        - `frequency` integer, required
      - `tax_mode` string
      - `unit_price` MoneyAmount, required
        - `amount` string, required
        - `currency_code` string, required
      - `unit_price_overrides` object[]
      - `quantity` QuantityConstraints
        - `minimum` integer, required
        - `maximum` integer, required
      - `status` string, required
      - `custom_data` object
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `import_meta` object
    - `product` PaddleBillingProduct, required
      - `id` string, required
      - `name` string, required
      - `type` string
      - `tax_category` string
      - `description` string
      - `image_url` string
      - `custom_data` object
      - `status` string, required
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `import_meta` object
    - `recurring` boolean
    - `trial_dates` object
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `next_billed_at` string, date-time
    - `previously_billed_at` string, date-time
  - `custom_data` object
  - `immediate_transaction` SubscriptionUpdateTransaction
    - `billing_period` BillingPeriod, required
      - `starts_at` string, date-time, required
      - `ends_at` string, date-time, required
    - `details` PaddleBillingTransactionDetails, required
      - `line_items` PaddleBillingTransactionLineItem[], required
        - `price_id` string, required
        - `product` PaddleBillingTransactionProduct, required
          - `id` string, required
          - `name` string, required
          - `description` string
          - `custom_data` object
          - `image_url` string
        - `quantity` integer, required
        - `totals` TransactionItemTotals, required
          - `discount` integer, required
          - `subtotal` integer, required
          - `tax` integer, required
          - `total` integer, required
        - `unit_totals` TransactionItemTotals, required
          - `discount` integer, required
          - `subtotal` integer, required
          - `tax` integer, required
          - `total` integer, required
        - `tax_rate` string
      - `totals` TransactionTotals, required
        - `subtotal` string, required
        - `tax` string, required
        - `discount` string, required
        - `total` string, required
        - `grand_total` string, required
        - `fee` string
        - `credit` string, required
        - `credit_to_balance` string, required
        - `balance` string, required
        - `earnings` string
        - `currency_code` string, required
  - `next_transaction` SubscriptionUpdateTransaction
    - `billing_period` BillingPeriod, required
      - `starts_at` string, date-time, required
      - `ends_at` string, date-time, required
    - `details` PaddleBillingTransactionDetails, required
      - `line_items` PaddleBillingTransactionLineItem[], required
        - `price_id` string, required
        - `product` PaddleBillingTransactionProduct, required
          - `id` string, required
          - `name` string, required
          - `description` string
          - `custom_data` object
          - `image_url` string
        - `quantity` integer, required
        - `totals` TransactionItemTotals, required
          - `discount` integer, required
          - `subtotal` integer, required
          - `tax` integer, required
          - `total` integer, required
        - `unit_totals` TransactionItemTotals, required
          - `discount` integer, required
          - `subtotal` integer, required
          - `tax` integer, required
          - `total` integer, required
        - `tax_rate` string
      - `totals` TransactionTotals, required
        - `subtotal` string, required
        - `tax` string, required
        - `discount` string, required
        - `total` string, required
        - `grand_total` string, required
        - `fee` string
        - `credit` string, required
        - `credit_to_balance` string, required
        - `balance` string, required
        - `earnings` string
        - `currency_code` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/pollination/apis/pollination-server.md) · [All operations](https://skmtc.net/pollination/apis/pollination-server/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pollination/pollination-server/revisions/c1f3c6d96b31/schema)