Subscriptions

Subscriptions are the heart of Gilbert. They represent the ongoing billing relationship between you and your customers, defining what they're paying for, how often, and at what price.

What is a Subscription?

A subscription connects a customer to one or more prices, creating a recurring billing relationship. Each billing period, Gilbert automatically generates an invoice based on the subscription's items.

A subscription defines:

• Customer — Who is being billed
• Currency — The billing currency (cannot be changed)
• Billing duration — How often to bill (can be changed via plan upgrades)
• Items — Prices with quantities

Creating Subscriptions

Subscription Lifecycle

Subscriptions move through these statuses:

New subscriptions start in Draft status, giving you time to review the configuration before billing begins. Draft subscriptions can be modified freely.

Activating

To start billing, activate the subscription:

1. Open the subscription
2. Click Activate
3. Choose trial options:
   • Plan default — Use the trial period from the plan (if any)
   • No trial — Start billing immediately
   • Custom — Set a specific trial duration
4. Confirm activation

Once activated, the subscription transitions to Trialing (if a trial was set) or Active. During a trial, the customer has access but no invoices are generated. When the trial ends, billing begins automatically.

Pausing & Resuming

You can pause a subscription immediately or schedule it to pause at the end of the current billing period.

Immediate Pause

• Subscription moves directly to Paused
• No further invoices until resumed

Scheduled Pause

• Subscription moves to Pausing status
• Customer retains access until the period ends
• Automatically becomes Paused when the period ends
• Can be reverted while still in Pausing status

Resuming

When you resume a paused subscription:

• A new billing period starts from the current time
• The subscription returns to Active status

Canceling

You can cancel a subscription immediately or schedule it to cancel at the end of the current billing period.

Immediate Cancel

• Subscription moves directly to Canceled
• Billing stops immediately

Scheduled Cancel

• Subscription moves to Cancelling status
• Customer retains access until the period ends
• Automatically becomes Canceled when the period ends
• Can be reverted while still in Cancelling status

Allowed Operations by Status

Not all operations are available in every status. This table summarizes what actions are permitted:

Attempting an operation not allowed for the current status returns an error.

Modifying Subscriptions

Draft Subscriptions

While in Draft status, you can freely modify:

• Add or remove items
• Change quantities
• Adjust any configuration

Active Subscriptions

After activation, you can still:

• Add new prices to the subscription
• Remove existing prices
• Adjust quantities

Changes to active subscriptions are typically prorated. See Proration for details.

Plan Changes

For plan-based subscriptions, you can change to a different plan:

1. Open the subscription
2. Click Change Plan
3. Select the new plan
4. Choose when to apply:
   • Immediately — Change takes effect now (with proration)
   • At renewal — Change takes effect at the next billing period
5. Confirm

See Proration for how mid-cycle changes are calculated.

Plan Change Constraints

Immediate Changes:

• Upgrades (longer or same billing duration) can be applied immediately
• Downgrades (shorter billing duration, e.g., yearly → monthly) must be scheduled

Scheduled Changes:

• Take effect at the next billing period
• Only one scheduled change can be pending at a time
• Can be reverted before it takes effect

Ad-hoc Subscriptions: Ad-hoc subscriptions (created without a plan) cannot change plans. To move to plan-based billing, cancel the ad-hoc subscription and create a new plan-based subscription.

Subscription Items

Each subscription contains one or more items. An item consists of:

• Price — The price being charged
• Quantity — How many units

For example:

Billing Behavior

Billing Anchor

The billing anchor is the reference date for billing cycles. It's set when the subscription is activated (or when a trial ends).

For example, if a monthly subscription activates on the 15th:

• First invoice: 15th of month 1
• Second invoice: 15th of month 2
• And so on

Automatic Renewal

Active subscriptions renew automatically. At each billing period, Gilbert:

1. Calculates the invoice amount
2. Creates and issues the invoice
3. Sends notification to the customer
4. Schedules the next renewal

Best Practices

Use Plans for Standard Offerings

Create plans for common subscription configurations. This ensures consistency and makes plan changes possible.

Start with Drafts

Create subscriptions as drafts first. This gives you a chance to review before activating and starting the billing cycle.

Handle Cancellations Gracefully

Use scheduled cancellations (at period end) rather than immediate cancellations when possible. This gives customers access through the end of their paid period.

Related

• Customers — Who subscriptions belong to
• Prices — What subscriptions charge
• Plans — Pre-configured subscription templates
• Invoices — Billing documents from subscriptions
• Billing Periods — How billing cycles work
• Proration — Mid-cycle change calculations