Bulk update subscriptions with AI

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