Trials

A Trial Subscription allows customers to use a product for a limited period before committing to a paid plan. During the trial, no charges are applied. BillHive manages the complete trial lifecycle — from creation through expiration or conversion to a paid subscription.

Trial Lifecycle

┌────────────────────────────┐
│  Trial Order Created       │
└────────────┬───────────────┘
             ▼
┌────────────────────────────┐
│  Trial Pending Activation  │──── Payment received ────▶ Trial → Active
└────────────┬───────────────┘                           (converted)
             │ Auto-activated
             ▼
┌────────────────────────────┐
│       Trial (Active)       │──── Trial Ending Soon ──▶ Notification sent
└────────────┬───────────────┘
             │
    ┌────────┴────────┐
    ▼                 ▼
┌──────────┐   ┌──────────────┐
│ Converted│   │ Trial Expired│
│ (Active) │   │              │
└──────────┘   └──────────────┘

Creating a Trial Subscription

When creating a subscription, enable the Is Trial toggle and configure:

FieldRequiredDescription
Is TrialYesEnable trial mode for this subscription
Trial PeriodYesDuration of the trial — term and period (e.g., 14 Days, 1 Month)

The subscription is created with status Trial and no charges are invoiced during the trial period.

Require billing at signup

A trial price can be set to Require billing at signup. When it is, a trial order placed without a payment method or Auto Collect is rejected with the message “This plan needs a payment method at signup”. Previewing the price still works without one. Paid signups are not affected.

Known limitation: for a free trial, Auto Collect does not yet set up a payment mandate at signup.

Unless the order says otherwise, a trial order has Auto Renew on, so the trial converts to a paid subscription.

Trial Statuses

StatusDescription
Trial Pending ActivationTrial order has been created but is awaiting payment method setup or mandate confirmation. If auto-renew is enabled, BillHive waits up to 5 days for payment.
TrialTrial is actively running. Customer has full access to the product.
Trial ExpiredTrial period ended without converting to a paid subscription.

Trial Ending Soon

BillHive sends a Trial Ending Soon notification before the trial expires. This gives the customer an opportunity to:

  • Add a payment method and convert to paid
  • Choose a plan if multiple options exist
  • Contact support with questions

The notification is triggered by the business event SUBSCRIPTION_TRIAL_ENDING_SOON (webhook Subscription.trial_ending_soon). It is sent Trial Expiring Soon Offset Days before the trial ends: a whole number from 1 to 60, default 5, set in Subscription Settings.

Trial Conversion

A trial converts to a paid subscription when payment is received before the trial expires:

  1. Customer adds a payment method or payment is collected.
  2. The trial activation workflow detects the payment.
  3. Subscription status changes from Trial → Active.
  4. A new billing term begins and the first invoice is generated.
  5. Activity logged as TRIAL_CONVERTED.

Auto-Renewal and Trial Conversion

Auto-RenewBehavior
EnabledAfter trial creation, BillHive waits up to 5 days for mandate/payment confirmation. If received, the trial activates and will auto-convert at trial end. If not received within 5 days, the trial is expired and the order is cancelled.
DisabledTrial runs for the configured period. If no payment is received by trial end, the subscription moves to Trial Expired.

Trial Expiration

When the trial period ends without conversion:

  1. Subscription status changes to Trial Expired.
  2. The associated order is cancelled.
  3. Activity logged as TRIAL_EXPIRED.
  4. Customer loses access (based on your Access Continuity setting).

Cancelling a Trial

A trial can be cancelled while its status is Trial, and only Immediately. To let a trial run out instead, turn off Auto Renew.

When you cancel a trial:

  1. The trial activation order is cancelled and its invoice, if any, is voided.
  2. The scheduled trial workflows are deleted.
  3. Any payment mandate is cancelled.
  4. The status changes to Cancelled and the trial term ends today.
  5. The cancellation notification is sent.

No credits or refunds are issued. Asking for End of Term or Specific Date returns an error: “A trial can only be cancelled immediately. To let it run out, turn off Auto Renew.”

Extending a Trial

A merchant can give a customer more time while the subscription is in Trial. Choose Extend trial on the subscription and pick a new end date. The date must be after the current trial end. There is no upper limit.

When you extend a trial:

  1. The trial term ends on the new date.
  2. The activation order moves to the day after the new end date.
  3. The “trial ending soon” step is set again, so it runs the usual number of days before the new end.
  4. An entry is added to the activity log with the old and new end dates, and the customer gets a “Trial extended” email.

Once the trial is Trial Pending Activation, the first payment is already under way and it can no longer be extended. The API returns an error: “The trial is already converting. Extend it before <date>.”

Customers cannot extend their own trial from the self-serve portal.

Converting early

A merchant can end a trial early and start billing at once. Choose Convert to paid now on a subscription in Trial.

  • The trial ends today and the paid term starts today.
  • The customer is billed in full for the first term. There is no credit for the unused trial days.
  • The “trial ending soon” step is removed, so the customer is billed only once.

The subscription moves to Trial Pending Activation while the first payment is collected, and then becomes Active. If the payment fails, the trial follows the same path as a trial that ended on its own.

Customers can convert from the self-serve portal only when the enableConvertTrial feature flag is turned on for the product. It is off by default.

Trial Analytics

Track trial performance on the Trial Conversion Rate dashboard:

  • Conversion rate — percentage of trials that convert to paid
  • Avg days to convert — how long it takes customers to decide
  • Conversion by plan — which plans have the best trial-to-paid conversion
  • Funnel visualization — drop-off between trial stages