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

# Extend or activate a trial

Extend a trial to give customers longer to evaluate, or cut a trial short to transition a customer to paying.

---

Trials let customers try your app or service before paying for it. You can extend trials to give customers more time to evaluate your app, or activate a subscription before a trial is up to transition a customer to paying.

Making it as easy as possible for trialing customers to transition to a paid plan is a simple way to reduce your CAC (customer acquisition cost).

{% callout type="note" %}
Change the items list against a subscription to add or remove items, update quantities, and bill for one-time charges. To learn more, see [Work with trials](https://developer.paddle.com/build/subscriptions/update-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, Paddle creates a subscription with the status `trialing`. The customer isn't charged right away. Instead, they're charged on the `next_billed_at` date against the subscription.

When the `next_billed_at` date elapses, Paddle charges the [payment method](https://developer.paddle.com/concepts/payment-methods/overview.md) on file and the subscription changes to `active`. The `current_billing_period` for trialing subscriptions is based on the trial period. On activation, it's updated so that it's based on the `billing_cycle`.

You can extend a trial by changing the `next_billed_at` date against a subscription to a date after this date.

You can cut a trial period short by either:

- Changing the `next_billed_at` date against a subscription to an earlier date.
- Sending a request to the [`/subscriptions/{subscription_id}/activate`](https://developer.paddle.com/api-reference/subscriptions/activate-subscription.md) endpoint to activate a subscription immediately.

Both options work for automatically-collected subscriptions. The [activate a trialing subscription operation](https://developer.paddle.com/api-reference/subscriptions/activate-subscription.md) only works for automatically-collected subscriptions, so you should move the billing date for manually-collected subscriptions.

Since customers aren't yet paying, [proration](https://developer.paddle.com/concepts/subscriptions/proration.md) doesn't apply when changing billing dates for a trial. 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 extend or activate 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.

## Extend or cut short a trial

Send a `PATCH` request to the `/subscriptions/{subscription_id}` endpoint to extend a trial.

In your request, include:

- `next_billed_at` with the new trial end date. Must be at least 30 minutes from now.
- `proration_billing_mode` set to `do_not_bill`, which is the only allowed value for trialing subscriptions.

Paddle updates the `next_billed_at` date for the subscription and items, and `current_billing_period` and `items[].trial_dates.ends_at`.

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

```json
{
  "next_billed_at": "2023-10-01T00:00:00Z",
  "proration_billing_mode": "do_not_bill"
}
```

```json
{
  "data": {
    "id": "sub_01h90n6j4k325zxf9rasr9rsb3",
    "status": "trialing",
    "customer_id": "ctm_01h84cjfwmdph1k8kgsyjt3k7g",
    "address_id": "add_01h90n5k7r3gzznv46h2nta7z0",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2023-08-29T12:44:51.731Z",
    "updated_at": "2023-08-29T12:53:28.538Z",
    "started_at": "2023-08-29T12:44:51.731Z",
    "first_billed_at": null,
    "next_billed_at": "2023-10-01T00:00:00Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2023-08-29T12:44:51.731Z",
      "ends_at": "2023-10-01T00:00:00Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "year"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "trialing",
        "quantity": 10,
        "recurring": true,
        "created_at": "2023-08-29T12:44:51.731Z",
        "updated_at": "2023-08-29T12:53:28.537Z",
        "previously_billed_at": null,
        "next_billed_at": "2023-10-01T00:00:00Z",
        "trial_dates": {
          "starts_at": "2023-08-29T12:44:51.731Z",
          "ends_at": "2023-10-01T00:00:00Z"
        },
        "price": {
          "id": "pri_01h84cdy3xatsp16afda2gekzy",
          "product_id": "pro_01h84cd36f900f3wmpdfamgv8w",
          "description": "Annual plan",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "year"
          },
          "trial_period": {
            "frequency": 10,
            "interval": "day"
          },
          "unit_price": {
            "amount": "0",
            "currency_code": "USD"
          }
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h90n6j4k325zxf9rasr9rsb3/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h90n6j4k325zxf9rasr9rsb3/cancel"
    },
    "discount": null
  },
  "meta": {
    "request_id": "2ec9fe96-bfc6-485b-8804-9e6950a32b42"
  }
}
```

{% /api-example %}

## Activate a trialing subscription

{% callout type="info" %}
Only automatically-collected subscriptions can be activated using the activate a subscription operation. For manually-collected subscriptions, follow the steps to [extend or cut short a trial](#extend-trial).
{% /callout %}

Activate a subscription to cut the trial period short and start charging a customer for it.

Activate a subscription using the API in two steps:

1. **Preview charging** {% badge label="Optional" variant="outline" /%}  
   Preview how much the customer is going to be charged on activation. Present this to customers if you offer in-app activation.
2. **Activate subscription**  
   Send a request to activate a subscription immediately.

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

Send a `GET` request to the `/subscriptions/{subscription_id}` endpoint, using the `include` query parameter with the `next_transaction` and `recurring_transaction_details` values to get a preview of what the customer is going to be charged when you activate the subscription.

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 in-app activation.

{% api-example method="GET" path="/subscriptions/{subscription_id}?include=next_transaction,recurring_transaction_details" href="/api-reference/subscriptions/get-subscription" %}

```json
{
  "data": {
    "id": "sub_01h90n6j4k325zxf9rasr9rsb3",
    "status": "trialing",
    "customer_id": "ctm_01h84cjfwmdph1k8kgsyjt3k7g",
    "address_id": "add_01h90n5k7r3gzznv46h2nta7z0",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2023-08-29T12:44:51.731Z",
    "updated_at": "2023-08-29T12:53:28.538Z",
    "started_at": "2023-08-29T12:44:51.731Z",
    "first_billed_at": null,
    "next_billed_at": "2023-10-01T00:00:00Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2023-08-29T12:44:51.731Z",
      "ends_at": "2023-10-01T00:00:00Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "year"
    },
    "recurring_transaction_details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "1000000",
            "discount": "0",
            "tax": "88750",
            "total": "1088750"
          }
        }
      ],
      "totals": {
        "subtotal": "1000000",
        "tax": "88750",
        "discount": "0",
        "total": "1088750",
        "fee": null,
        "credit": "0",
        "balance": "1088750",
        "grand_total": "1088750",
        "earnings": null,
        "currency_code": "USD",
        "exchange_rate": "1"
      },
      "line_items": [
        {
          "price_id": "pri_01h84cdy3xatsp16afda2gekzy",
          "quantity": 10,
          "totals": {
            "subtotal": "1000000",
            "tax": "88750",
            "discount": "0",
            "total": "1088750"
          },
          "product": {
            "id": "pro_01h84cd36f900f3wmpdfamgv8w",
            "name": "ChatApp Essential",
            "description": "Our starter plan — ideal for small teams for who are just starting out.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "100000",
            "discount": "0",
            "tax": "8875",
            "total": "108875"
          }
        }
      ]
    },
    "next_transaction": {
      "billing_period": {
        "starts_at": "2023-10-01T00:00:00Z",
        "ends_at": "2024-10-01T00:00:00Z"
      },
      "details": {
        "tax_rates_used": [
          {
            "tax_rate": "0.08875",
            "totals": {
              "subtotal": "1000000",
              "discount": "0",
              "tax": "88750",
              "total": "1088750"
            }
          }
        ],
        "totals": {
          "subtotal": "1000000",
          "tax": "88750",
          "discount": "0",
          "total": "1088750",
          "fee": null,
          "credit": "0",
          "balance": "1088750",
          "grand_total": "1088750",
          "earnings": null,
          "currency_code": "USD",
          "exchange_rate": "1"
        },
        "line_items": [
          {
            "price_id": "pri_01h84cdy3xatsp16afda2gekzy",
            "quantity": 10,
            "totals": {
              "subtotal": "1000000",
              "tax": "88750",
              "discount": "0",
              "total": "1088750"
            },
            "product": {
              "id": "pro_01h84cd36f900f3wmpdfamgv8w",
              "name": "ChatApp Essential",
              "description": "Our starter plan — ideal for small teams for who are just starting out.",
              "tax_category": "standard",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
              "status": "active"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "100000",
              "discount": "0",
              "tax": "8875",
              "total": "108875"
            }
          }
        ]
      },
      "adjustments": []
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "trialing",
        "quantity": 10,
        "recurring": true,
        "created_at": "2023-08-29T12:44:51.731Z",
        "updated_at": "2023-08-29T12:53:28.537Z",
        "previously_billed_at": null,
        "next_billed_at": "2023-10-01T00:00:00Z",
        "trial_dates": {
          "starts_at": "2023-08-29T12:44:51.731Z",
          "ends_at": "2023-10-01T00:00:00Z"
        },
        "price": {
          "id": "pri_01h84cdy3xatsp16afda2gekzy",
          "product_id": "pro_01h84cd36f900f3wmpdfamgv8w",
          "description": "Annual plan",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "year"
          },
          "trial_period": {
            "frequency": 10,
            "interval": "day"
          },
          "unit_price": {
            "amount": "0",
            "currency_code": "USD"
          }
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h90n6j4k325zxf9rasr9rsb3/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h90n6j4k325zxf9rasr9rsb3/cancel"
    },
    "discount": null
  },
  "meta": {
    "request_id": "a587bb7e-7f1f-418b-ba83-201768796d5b"
  }
}
```

{% /api-example %}

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

Send a `POST` request to the `/subscriptions/{subscription_id}/activate` endpoint to activate a subscription immediately. No request body needed.

Paddle activates the subscription immediately.

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

```json
{
  "data": {
    "id": "sub_01hv915hmgnwqd9n5yxgy8t60c",
    "status": "active",
    "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j",
    "address_id": "add_01hv914saqwe9wk1sbxyy9q7kq",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2024-04-12T11:30:29.648Z",
    "updated_at": "2024-04-12T11:31:10.027Z",
    "started_at": "2024-04-12T11:30:29.637Z",
    "first_billed_at": "2024-04-12T11:31:09.996Z",
    "next_billed_at": "2024-05-12T11:31:09.996Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2024-04-12T11:31:09.996Z",
      "ends_at": "2024-05-12T11:31:09.996Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 10,
        "recurring": true,
        "created_at": "2024-04-12T11:30:29.648Z",
        "updated_at": "2024-04-12T11:31:10.029Z",
        "previously_billed_at": "2024-04-12T11:31:09.996Z",
        "next_billed_at": "2024-05-12T11:31:09.996Z",
        "trial_dates": {
          "starts_at": "2024-04-12T11:30:29.637Z",
          "ends_at": "2024-04-12T11:31:09.996Z"
        },
        "price": {
          "id": "pri_01hv0vax6rv18t4tamj848ne4d",
          "product_id": "pro_01htz88xpr0mm7b3ta2pjkr7w2",
          "type": "standard",
          "description": "Monthly (per seat) with 14 day trial",
          "name": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": {
            "frequency": 14,
            "interval": "day",
            "requires_payment_method": false
          },
          "unit_price": {
            "amount": "500",
            "currency_code": "USD"
          },
          "unit_price_overrides": [
            {
              "country_codes": ["IE", "FR", "DE"],
              "unit_price": {
                "amount": "700",
                "currency_code": "EUR"
              }
            },
            {
              "country_codes": ["GB"],
              "unit_price": {
                "amount": "600",
                "currency_code": "GBP"
              }
            }
          ],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "import_meta": null,
          "created_at": "2024-04-09T07:14:38.424504Z",
          "updated_at": "2024-04-09T07:15:53.950721Z"
        },
        "product": {
          "id": "pro_01htz88xpr0mm7b3ta2pjkr7w2",
          "name": "AeroEdit for learner pilots",
          "type": "standard",
          "tax_category": "standard",
          "description": "Essential tools for student pilots to manage flight logs, analyze performance, and plan routes, and ensure compliance. Valid student pilot certificate from the FAA required.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png",
          "custom_data": {
            "features": {
              "aircraft_performance": true,
              "compliance_monitoring": false,
              "flight_log_management": true,
              "payment_by_invoice": false,
              "route_planning": true,
              "sso": false
            },
            "suggested_addons": [
              "pro_01h1vjes1y163xfj1rh1tkfb65",
              "pro_01gsz97mq9pa4fkyy0wqenepkz"
            ],
            "upgrade_description": null
          },
          "status": "active",
          "import_meta": null,
          "created_at": "2024-04-08T16:22:16.024Z",
          "updated_at": "2024-04-08T16:27:59.074Z"
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hv915hmgnwqd9n5yxgy8t60c/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hv915hmgnwqd9n5yxgy8t60c/cancel"
    },
    "discount": null,
    "import_meta": null
  },
  "meta": {
    "request_id": "8e6362d5-caaa-43d9-8ec5-f912c35b697d"
  }
}
```

{% /api-example %}