> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Bulk update subscriptions
> Learn how to add products or make changes to multiple subscriptions at once using the API
When you need to apply the same change to multiple subscriptions—such as adding a new product to all customers—you have several options depending on your use case and requirements.
## Overview of methods
| Method | Best for | Pros | Cons |
| --------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------ | ------------------------------- |
| [Update full subscription](#update-full-subscription) | Simple bulk updates with no pro-rata invoicing | Versioning, no transition invoice, keeps billing cycle | — |
| [Create a subscription transition](#create-a-subscription-transition) | Full control with versioning and billing options | Version history, flexible configuration | Advanced setup |
| [Incremental update (deprecated)](#incremental-update-deprecated) | Legacy use cases | Simple | No versioning, not future-proof |
## Update full subscription
**Recommended for most bulk update scenarios.**
The `PUT /v2/subscriptions/:id` endpoint performs an immediate transition while keeping the billing cycle and waiving the transition invoice. This means no pro-rata invoice is generated.
You want to add a new "Support" product to all active subscriptions. Using this method, the product is added immediately without generating pro-rata charges, and customers continue on their existing billing cycle.
### How it works
1. Fetch the subscription using `GET /v2/subscriptions/:id` to get its current configuration
2. Add the new product to the subscription phases
3. Call `PUT /v2/subscriptions/:id` with the full updated subscription payload
The payload structure matches the response from `GET /v2/subscriptions/:id`, allowing you to retrieve a subscription, modify it, and update it using the same structure.
```sh theme={null}
curl -X PUT "https://api.hyperline.co/v2/subscriptions/{subscription_id}" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"phases": [
{
"id": "phase_xxx",
"products": [
...
{
"product_id": "prod_new_product_id",
"price": {
"type": "flat_fee",
"amount": 1000,
"interval": "month"
}
}
],
...
}
],
... // Existing subscription payload
}'
```
### When to use
* Adding a product to multiple subscriptions without pro-rata billing
* Making simple configuration changes across subscriptions
* When you want version history with minimal configuration
## Create a subscription transition
Use the transition endpoint when you need full control over the update process, including billing options.
### Option A: Pass the full subscription configuration
Call `POST /v2/subscriptions/transitions` with the source subscription and target subscription configuration including the new product.
```sh theme={null}
curl -X POST "https://api.hyperline.co/v2/subscriptions/transitions" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"source_subscription_id": "sub_xxx",
"application_schedule": "immediately",
"billing_cycle_transition_method": "keep_current_billing_cycle",
"calculation_method": "do_not_charge",
"target_subscription": {
"phases": [
{
"products": [
...
],
...
}
],
... // Existing subscription payload
}
}'
```
### Option B: Transition to an updated template/plan
If the subscription was created from a template or plan and **has not been customized since**, and you've already updated that template/plan with the new product, you can transition the subscription to use the updated template.
You have 100 customers on the "Pro Plan" template. You add a new "Analytics" product to the Pro Plan template. Instead of specifying the full subscription configuration for each customer, you transition each subscription to the updated Pro Plan template.
```sh theme={null}
curl -X POST "https://api.hyperline.co/v2/subscriptions/transitions" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"source_subscription_id": "sub_xxx",
"application_schedule": "immediately",
"billing_cycle_transition_method": "keep_current_billing_cycle",
"calculation_method": "do_not_charge",
"target_subscription": {
"subscription_template_id": "template_xxx"
}
}'
```
This approach is efficient when many subscriptions share the same template, as you only need to pass the template ID rather than the full subscription configuration.
### Transition options
| Parameter | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------- |
| `application_schedule` | When to apply: `immediately` or `scheduled` (with `transition_date`) |
| `billing_cycle_transition_method` | `keep_current_billing_cycle` to keep current billing dates, `align_to_new_billing_cycle` to reset |
| `calculation_method` | `do_not_charge` to skip transition invoice, `pro_rata` to generate pro-rata invoice |
## Incremental update (deprecated)
The `POST /v1/subscriptions/:id/update-many` endpoint is deprecated. It lacks versioning and is not future-proof. Use one of the methods above instead.
This endpoint allows updating multiple aspects of a subscription in a single call but does not maintain version history.
## Scripting bulk updates
To update multiple subscriptions, write a script that:
1. Lists all target subscriptions using `GET /v2/subscriptions` with appropriate filters
2. For each subscription, applies the update using your chosen method
3. Handles errors and retries as needed
Use pagination and rate limiting in your script. See the [rate limiting documentation](/api-reference/docs/rate-limiting) for details.
Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support.