> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Work with trials

Add or remove recurring items, change quantities, and bill for one-time charges for subscriptions in trial. You can also pause trialing subscriptions, too.

---

Trials let customers try your app or service before paying for it. You can update trialing subscriptions to make changes to what a customer is billed for when they transition to a paid plan. You can also bill one-time charges to a subscription for things like data import or setup fees.

We recommend letting customers make changes to a trialing subscription as part of a workflow where they confirm and activate their subscription.

{% callout type="note" %}
Change the next billing date against a trialing subscription to extend or cut short the trial period. You can also activate a trialing subscription right away using the API. To learn more, see [Extend or activate a trial](https://developer.paddle.com/build/subscriptions/extend-activate-change-date-trials.md)
{% /callout %}

## How it works

When [customers complete checkout](https://developer.paddle.com/build/checkout/pass-update-checkout-items.md) for recurring items with a trial period, or you [issue an invoice](https://developer.paddle.com/build/invoices/create-issue-invoices.md) for items with a trial period, Paddle creates a subscription with the status `trialing`.

You can make changes to trialing subscriptions to pause, add or remove items, change quantities, and bill for one-time charges. This lets you handle:

- **Upgrades or downgrades**  
  Replacing items on a subscription to let customers upgrade or downgrade their plan while they're in trial.
- **Adding, removing, or changing items**  
  Add or remove additional modules, or update quantities for seats or users before going live.
- **Bill for one-time charges**  
  Charge for things like data import or setup fees during a trial period.
- **Pause at the end of the trial period**  
  Preserve any work a customer did in your app in trial if they're not ready to go live right away.

Since customers aren't yet paying, [proration](https://developer.paddle.com/concepts/subscriptions/proration.md) doesn't apply when making changes to a trialing subscription. You must use `do_not_bill` as the `proration_billing_mode` when sending requests.

{% callout type="info" %}
Only the `items` and `next_billed_at` fields can be updated for a subscription in trial. You can't update other fields against a subscription until it's activated.
{% /callout %}

## Before you begin

To make changes to items on a trialing subscription, you'll need to [get the subscription ID](https://developer.paddle.com/api-reference/subscriptions/list-subscriptions.md) for the subscription you want to change.

You can use the `status` query parameter when listing with the value `trialing` to get a list of subscriptions in trial.

## Update items

Update items on a trialing subscription to make changes to what a customer is billed for when activated. Replace items on a subscription to [upgrade or downgrade](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md); or [add, remove, or change items](https://developer.paddle.com/build/subscriptions/add-remove-products-prices-addons.md) to change how Paddle bills for recurring products like additional modules or seats.

Update items on a trialing subscription using the API in three steps:

1. **Extract existing items**  
   Get the existing items on the subscription to extract the `price.id` and `quantity` for each item.
2. **Preview change** {% badge label="Optional" variant="outline" /%}  
   Preview how much the customer is going to be charged on a regular basis. Present this to customers if you offer an in-app workflow to update items.
3. **Update subscription**  
   Send a request to update the subscription with the changes you previewed.

{% callout type="note" %}
For examples and specific guidance, see [Add or remove items](https://developer.paddle.com/build/subscriptions/add-remove-products-prices-addons.md) or [Upgrade or downgrade](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md).
{% /callout %}

### Extract existing items {% step=true %}

Send a `GET` request to the `/subscriptions/{subscription_id}` endpoint to get the existing items on the subscription. Extract the `price.id` and `quantity` for each item in the `items` array — you'll need these to build your update request.

{% callout type="note" %}
We recommend storing product and price IDs in your database as part of provisioning a subscription. This means you don't need to extract them from the API when updating items on a subscription.
{% /callout %}

{% api-endpoint method="GET" path="/subscriptions/{subscription_id}" href="/api-reference/subscriptions/get-subscription" /%}

### Preview change {% step=true badge="Optional" %}

Send a `PATCH` request to the `/subscriptions/{subscription_id}/preview` endpoint to preview the changes you're making to the subscription.

In your request, include:

- `items`: An array of items you want on the subscription. Each item should include a `price_id` and `quantity`.
- `proration_billing_mode`: Set to `do_not_bill`, which is the only allowed value for trialing subscriptions.

The response includes:

- `next_transaction`: An object with a preview of the next transaction for this subscription. May include charges that aren't yet billed.
- `recurring_transaction_details`: An object with a preview of the recurring transaction for this subscription. This is what the customer can expect to be billed when there's no prorated or one-time charges.

You should present this to customers if you offer an in-app workflow to update items.

{% api-endpoint method="PATCH" path="/subscriptions/{subscription_id}/preview" href="/api-reference/subscriptions/preview-subscription" /%}

### Update subscription {% step=true %}

Send a `PATCH` request to the `/subscriptions/{subscription_id}` endpoint to update the subscription.

In your request, include the same body as the preview request.

Paddle updates the subscription.

{% api-endpoint method="PATCH" path="/subscriptions/{subscription_id}" href="/api-reference/subscriptions/update-subscription" /%}

## Bill for one-time charges

Bill a one-time charge to a trialing subscription for things like onboarding or setup fees.

Bill for one-time charges using the API in two steps:

1. **Preview charge** {% badge label="Optional" variant="outline" /%}  
   Preview how much the customer is going to be charged for the one-time charge. Present this to customers if you offer a way to bill for one-time charges in your app.
2. **Create one-time charge**  
   Send a request to bill for the one-time charge.

{% callout type="note" %}
For a complete overview with examples, see [Bill for one-time charges](https://developer.paddle.com/build/subscriptions/bill-add-one-time-charge.md).
{% /callout %}

### Preview charge {% step=true stepReset=true badge="Optional" %}

Send a `POST` request to the `/subscriptions/{subscription_id}/charge/preview` endpoint to preview the one-time charge.

In your request, include:

- `items`: An array of one-time items you want to bill for. Each item should include a `price_id` and `quantity`. You don't need to include existing recurring items.
- `effective_from`: Set to `immediately` to create a transaction right away, or `next_billing_period` to add charges to the next renewal transaction.

The response includes:

- `next_transaction`: An object with a preview of the next transaction for this subscription. May include charges that aren't yet billed.
- `recurring_transaction_details`: An object with a preview of the recurring transaction for this subscription. This is what the customer can expect to be billed when there's no prorated or one-time charges.

You should present this to customers if you offer a way to bill for one-time charges in your app.

{% api-endpoint method="POST" path="/subscriptions/{subscription_id}/charge/preview" href="/api-reference/subscriptions/preview-charge" %}
{% /api-endpoint %}

### Create one-time charge {% step=true %}

Send a `POST` request to the `/subscriptions/{subscription_id}/charge` endpoint to bill for the one-time charge.

In your request, include the same body as the preview request.

Paddle bills for the one-time charge.

{% api-endpoint method="POST" path="/subscriptions/{subscription_id}/charge" href="/api-reference/subscriptions/charge-subscription" /%}

## Pause at the end of the trial period

Pause a trialing subscription at the end of the trial period to preserve any work a customer did in your app in trial if they're not ready to go live right away. Paddle bills for the subscription on resume.

Send a `POST` request to the `/subscriptions/{subscription_id}/pause` endpoint to pause the subscription.

{% callout type="note" %}
For more information and examples, see [Pause a subscription](https://developer.paddle.com/build/subscriptions/pause-subscriptions.md).
{% /callout %}

{% api-endpoint method="POST" path="/subscriptions/{subscription_id}/pause" href="/api-reference/subscriptions/pause-subscription" /%}