Subscriptions

A Subscription represents a customer’s ongoing agreement to pay for a product at a specific rate plan, currency, and billing frequency. Subscriptions are the central entity in BillHive — invoices, payments, usage events, and orders all revolve around them.

Creating a Subscription

URL: /subscriptions/add or /customers/{customerId}/subscription/add

1. Navigate to a customer’s page and click Add Subscription, or go to Subscriptions > Add.
2. Fill in the subscription form:

3. Review addons — mandatory addons are automatically included; recommended addons can be toggled on/off.
4. Review the order estimate showing pricing, prorations, and totals.
5. Click Place Order to create the subscription.

Backdated Start Dates

When you onboard an existing customer, you can create a subscription that started in the past.

• Who can backdate. Only admin channels (the BillHive web app and the API). Subscriptions created from the public checkout (Website) or the Self-Serve Portal cannot start in the past.
• How far back. Up to the tenant’s Backdate lookback (days) setting, which defaults to 90 (see Subscription Settings). A start date today or in the future is not affected by the limit.
• Rejected dates. A start date older than the limit, or any past date from a non-admin channel, is rejected with HTTP 400, for example Start date 2026-06-01 is more than 90 days in the past (tenant lookback limit).

For a backdated start:

• The first term runs from the start date for one billing period (for example, a monthly plan started 30 days ago has a term from that date to the day before its first monthly anniversary), not from today.
• The first invoice is dated the start date. Its due date still counts from the day it is issued, so a Net 30 invoice is due 30 days after you create it.
• The subscription starts Active, and days already elapsed in the term are counted as used.
• Only the first term is billed. If the start date is so far back that the term has already ended, the subscription is created with that ended term, and renewal picks up from there: each renewal creates the next term starting the day after the previous one ends, so later terms are billed one at a time rather than all at once.
• Trial plans are not backdated: the trial starts today.

Viewing a Subscription

URL: /customers/{customerId}/subscriptions/{subscriptionId}

The subscription details page is organized into tabs:

Subscription Details (Home Tab)

The home tab displays:

• Subscription ID — Unique identifier
• Product & Rate Plan — What the customer subscribed to
• Currency — Billing currency
• Amount — Current subscription amount
• Billing Period — Frequency and term details
• Term Dates — Start date, end date, and a visual progress bar showing days used vs. days remaining
• Auto Renew — Whether the subscription renews automatically
• Status — Current lifecycle status with color-coded badge
• Addons — List of active addons with applicability (Mandatory / Recommended), pricing model, quantity, price, and individual status

Subscriptions List

URL: /subscriptions (all subscriptions) or within a customer’s page

The subscriptions table shows:

Supports pagination (10 per page), full-text search, and sorting by last updated.

Subscription Statuses