Bulk update subscriptions

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	Simple bulk updates with no pro-rata invoicing	Versioning, no transition invoice, keeps billing cycle	—
Create a subscription transition	Full control with versioning and billing options	Version history, flexible configuration	Advanced setup
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.

Example 💡

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

Fetch the subscription using GET /v2/subscriptions/:id to get its current configuration
Add the new product to the subscription phases
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.

curl -X PUT "https://api.hyperline.co/v2/subscriptions/{subscription_id}" \
  -H "Authorization: Bearer <API key>" \
  -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.

curl -X POST "https://api.hyperline.co/v2/subscriptions/transitions" \
  -H "Authorization: Bearer <API key>" \
  -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.

Example 💡

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.

curl -X POST "https://api.hyperline.co/v2/subscriptions/transitions" \
  -H "Authorization: Bearer <API key>" \
  -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:

Lists all target subscriptions using GET /v2/subscriptions with appropriate filters
For each subscription, applies the update using your chosen method
Handles errors and retries as needed

Use pagination and rate limiting in your script. See the rate limiting documentation 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.

Implement Hyperline

Working with AI

Subscriptions

CPQ

Tips & Tricks

Bulk update subscriptions

Overview of methods

Update full subscription

Example 💡

How it works

When to use

Create a subscription transition

Option A: Pass the full subscription configuration

Option B: Transition to an updated template/plan

Example 💡

Transition options

Incremental update (deprecated)

Scripting bulk updates

​Overview of methods

​Update full subscription

Example 💡

​How it works

​When to use

​Create a subscription transition

​Option A: Pass the full subscription configuration

​Option B: Transition to an updated template/plan

Example 💡

​Transition options

​Incremental update (deprecated)

​Scripting bulk updates

Overview of methods

Update full subscription

How it works

When to use

Create a subscription transition

Option A: Pass the full subscription configuration

Option B: Transition to an updated template/plan

Transition options

Incremental update (deprecated)

Scripting bulk updates