Subscription Workflows
Last reviewed: 16 November 2026
Each workflow below lists its trigger, inputs, steps, rules, records changed, notifications and common errors. “Records changed” names the business records BillHive creates or updates.
Product to plan configuration
| Trigger | A new offering or price change |
| Input | Product name, plans, prices per currency and frequency |
| Rules | A price must be Active to be sold. Changing a list price doesn’t change existing subscriptions; they renew at their own term price |
| Records changed | Product, rate plan, rate plan price, components, add-ons, features |
| Errors | Builder validation messages, e.g. Pack size must be above 0; a v1 edit of a v2 price returns 409 |
Guide: Catalogue, Price Components.
Customer to subscription (activation)
| Trigger | Admin adds a subscription, customer completes checkout, or POST /{accountId}/subscriptions |
| Input | Account, rate plan price, quantity, add-ons, offers, start date, Auto Collect, Auto Renew |
| Rules | Backdating up to the Backdating limit; trial prices with Require billing at signup need a payment method; custom prices only with Price Override on and not by API key |
| Decisions | Future vs now; trial vs paid; Auto Collect vs manual; Activate before first payment |
| Records changed | Order, subscription and first term, invoice, payment request, activity log |
| Notifications | Subscription Created email; Subscription Activated webhook |
| Errors | This plan needs a payment method at signup; Custom prices are not allowed for this request |
Trial to paid conversion
| Trigger | Trial end date, or Convert to Paid Now |
| Rules | Extend only while Trial; the new end must be later. Converting now bills a full first term, no credit for unused trial days. No plan or frequency change during a trial |
| Records changed | Trial term end, activation order, first invoice |
| Errors | The trial is already converting. Extend it before <date>. |
Upgrade and downgrade
| Trigger | Admin, self-serve portal or API |
| Input | New price, timing, add-ons, offer |
| Rules | Active only. Same billing period: prorated if Prorated Billing for Upgrade/Downgrade is on. Different billing period: a new term starts on the change date. A Specific Date must fall within the current term. The newest action wins: a new change replaces a scheduled one |
| Records changed | Change order, subscription plan and term, add-on records, invoice or credit memo |
| Notifications | Plan Upgraded / Plan Downgraded / Change Scheduled; Subscription Changed webhook |
| Errors | Cannot change the plan of a subscription that is Paused.; A plan change is still being processed |
Detail: Plan & Frequency Changes.
Pause and resume
| Rules | Resume date at least 2 days ahead. Pausing discards a scheduled plan change, and the reverse. No invoices while paused |
| Records changed | Subscription status, term end, renewal order, scheduled workflows |
| Notifications | Subscription Paused, Subscription Resumed |
| Errors | No scheduled pause; A plan change is still being processed |
Cancellation
| Records changed | Cancel order, credit memo (Subscription Cancellation), ETF charge, refund, subscription status |
| Notifications | Cancellation Scheduled or Subscription Cancelled; Post Cancellation later |
| Errors | A trial can only be cancelled immediately…; notice-period rejection with the earliest allowed date |
Renewal
| Rules | Renews at the current term’s price; carried offers follow their duration; a Fixed price stops after its term length; in-arrears lines are added at the boundary |
| Records changed | Renewal order, new term, invoice |
| Errors | Edit Next Billing Date refused while a change, cancellation or pause is scheduled |