> ## 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 with AI

> AI skill for planning, confirming, applying, and verifying bulk subscription updates in Hyperline without breaking customer billing.

Use this skill when an AI assistant needs to update many subscriptions with the same change, such as adding a product, changing pricing, or transitioning subscriptions to a new configuration.

## Skill

```md theme={null}
---
name: bulk-update-subscriptions
description: Plan and execute safe bulk subscription updates in Hyperline. Use when an agent needs to identify subscriptions, preview or apply transitions, update subscriptions, and verify results across many records.
---

# Bulk Update Subscriptions

Bulk updates can affect billing and invoices. Plan first, execute only after explicit confirmation.

## Inputs

Collect these values before making changes:

- Target cohort: filters, customer list, subscription IDs, plan, product, status, or segment.
- Desired change: product, price, phase, template, billing behavior, or contract change.
- Effective date: immediately or scheduled date.
- Billing behavior: no charge, pro-rata charge, custom charge, or keep current billing cycle.
- Dry-run requirement: default to preview or sample first.

## Workflow

1. List candidate subscriptions using read-only filters.
2. Show the count and a small sample.
3. Ask the user to confirm the exact cohort before mutation.
4. Choose the safest update method:
   - Use `PUT /v2/subscriptions/{id}` for simple full-subscription updates with no transition invoice.
   - Use `POST /v2/subscriptions/transitions` when billing behavior, schedule, or pro-rata handling matters.
   - Use template-based transition only when subscriptions still match the source template and the template has already been updated.
5. Preview where possible.
6. Apply in bounded batches.
7. Verify updated subscriptions and summarize successes and failures.

## Safety

- Never run an unbounded update.
- Never mutate before showing the matched cohort and receiving confirmation.
- Do not use deprecated incremental update endpoints.
- Do not assume no invoice will be generated; choose and document the billing behavior.
- Stop on repeated failures and summarize the partial result.

## Output

Return:

- Cohort definition.
- Update method.
- Billing behavior.
- Batch result summary.
- Failed subscription IDs with errors.
- Verification checks performed.
```

## Related documentation

<CardGroup cols={2}>
  <Card title="Bulk update subscriptions guide" icon="arrows-rotate" href="/guides/bulk-update-subscriptions">
    Learn the supported bulk update patterns.
  </Card>

  <Card title="Create subscription transition API" icon="code" href="/api-reference/endpoints/subscriptions->-transitions/create-subscription-transition">
    Use transitions for controlled subscription changes.
  </Card>
</CardGroup>