WorkflowsSubscription Workflows

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

TriggerA new offering or price change
InputProduct name, plans, prices per currency and frequency
RulesA price must be Active to be sold. Changing a list price doesn’t change existing subscriptions; they renew at their own term price
Records changedProduct, rate plan, rate plan price, components, add-ons, features
ErrorsBuilder 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)

TriggerAdmin adds a subscription, customer completes checkout, or POST /{accountId}/subscriptions
InputAccount, rate plan price, quantity, add-ons, offers, start date, Auto Collect, Auto Renew
RulesBackdating 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
DecisionsFuture vs now; trial vs paid; Auto Collect vs manual; Activate before first payment
Records changedOrder, subscription and first term, invoice, payment request, activity log
NotificationsSubscription Created email; Subscription Activated webhook
ErrorsThis plan needs a payment method at signup; Custom prices are not allowed for this request

Trial to paid conversion

TriggerTrial end date, or Convert to Paid Now
RulesExtend 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 changedTrial term end, activation order, first invoice
ErrorsThe trial is already converting. Extend it before <date>.

Upgrade and downgrade

TriggerAdmin, self-serve portal or API
InputNew price, timing, add-ons, offer
RulesActive 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 changedChange order, subscription plan and term, add-on records, invoice or credit memo
NotificationsPlan Upgraded / Plan Downgraded / Change Scheduled; Subscription Changed webhook
ErrorsCannot change the plan of a subscription that is Paused.; A plan change is still being processed

Detail: Plan & Frequency Changes.

Pause and resume

RulesResume date at least 2 days ahead. Pausing discards a scheduled plan change, and the reverse. No invoices while paused
Records changedSubscription status, term end, renewal order, scheduled workflows
NotificationsSubscription Paused, Subscription Resumed
ErrorsNo scheduled pause; A plan change is still being processed

Cancellation

Records changedCancel order, credit memo (Subscription Cancellation), ETF charge, refund, subscription status
NotificationsCancellation Scheduled or Subscription Cancelled; Post Cancellation later
ErrorsA trial can only be cancelled immediately…; notice-period rejection with the earliest allowed date

Renewal

RulesRenews 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 changedRenewal order, new term, invoice
ErrorsEdit Next Billing Date refused while a change, cancellation or pause is scheduled