Skip to main content
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

MethodBest forProsCons
Update full subscriptionSimple bulk updates with no pro-rata invoicingVersioning, no transition invoice, keeps billing cycle—
Create a subscription transitionFull control with versioning and billing optionsVersion history, flexible configurationAdvanced setup
Incremental update (deprecated)Legacy use casesSimpleNo 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

  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. 
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

ParameterDescription
application_scheduleWhen to apply: immediately or scheduled (with transition_date)
billing_cycle_transition_methodkeep_current_billing_cycle to keep current billing dates, align_to_new_billing_cycle to reset
calculation_methoddo_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 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.