Subscriptions

A subscription is a recurring charge for a product or service that is billed at regular intervals, such as monthly or annually. These periods are referred to as service periods. An invoice is generated for each service period. Example: A monthly pre-paid subscription to an internet service provider.

Subscription status

This section describes all subscription statuses.

Subscription example: A monthly subscription to an internet service that is charged at 20 USD per month.

status describes the state of a subscription. The following are all statuses.

All subscription status transitions

The following diagram describes all states of a subscription.

Trial-only subscription

This section describes the subscription service states of a trial-only subscription.

1. A customer signs up to a subscription. The subscription is assigned the pending status.
2. The customer verifies a payment instrument, the customer's payment instrument is charged, or the subscription startTime is exceeded. The subscription is assigned the active status.
3. The subscription exceeds the trail period. The subscription is assigned the trial-ended status.
   When the trail is concluded the customer can choose to sign up to the subscription subscription or to stop using the product.

Paused subscription

This section describes the service states of a paused subscription. For more information, see Pause subscriptions or the Pause a subscription API operation.

1. A customer signs up to a subscription. The subscription is assigned the pending status.
2. The customer pays the first invoice. The subscription is assigned the active status.
3. The customer pauses their subscription. The subscription is assigned the paused status.
4. The customer resumes their subscription, or the pause end date is reached and the subscription automatically resumes. The subscription is assigned the active status.

Canceled subscription

This section describes the service states of a canceled subscription.

1. A customer signs up to a subscription. The subscription is assigned the pending status.
2. The customer pays the first invoice. The subscription is assigned the active status.
3. The customer decides to cancel their subscription. The subscription is assigned the canceled status. The subscription retains this status until the time remaining on the last paid subscription period expires. In this state, the customer is still subscribed to the service and can opt to reactivate the subscription.
4. The time remaining on the last paid subscription period expires. The subscription is assigned the churned status. The customer is no longer subscribed to the service but can still reactivate the subscription.

Abandoned subscription

This section describes the service states of an abandoned subscription.

Use the abandoned status to differentiate between intentionally voided subscriptions and pending subscriptions that are automatically abandoned due to inactivity.

1. A customer signs up to a subscription. The subscription is assigned the pending status.
2. The subscription is assigned an abandonTime value during subscription creation or based on the organization billing settings.
3. The abandon time is reached, and the subscription is automatically assigned the abandoned status. Associated invoices are voided.

Completed subscription

This section describes the service states of a completed subscription.

1. A customer signs up to a subscription. The subscription is assigned the pending status.
2. The customer pays the first invoice. The subscription is assigned the active status.
3. The subscription service period is concluded. The subscription is assigned the completed status. From this state, the customer can opt to begin a new subscription.

Manage subscriptions

This section describes how to manage subscriptions.

For more information on the UI, see Manage billing.

Service period anchor, billing timing, and invoice time shift

The following properties are used to configure subscriptions:

• Service period anchor: Used, in conjunction with the start time, to calculate the service period.

• Billing timing: Used to determine when, relative to the service period date, the invoice is issued. Billing timing controls whether the service is prepaid in advance or postpaid in arrears. In most scenarios, the service period anchor is aligned with the billing period. For example, the service period ends on the 1st of the month, and is billed on the 1st of the month.

• Invoice time shift: Used to adjust invoice issue and due date when billing must occur before the service period changes. For example, rent must be paid in advance, so the invoice must be in advance of the billing date. For more information, see Invoice time and due time shift.

Subscription renewals

Rebilly automates the scheduling and generation of renewal invoices. If autopay is active, the payment against the invoices is scheduled automatically. To stay informed on changes to the subscription, or when invoices get paid, see Webhooks.

Alternatively, use the UI to automate notifications and related tasks. For more information, see Invoice paid and Subscription activated.

Cancel a subscription

Select from the following cancellation options:

• Use the API to cancel a subscription — see Cancel an order.
• Use the UI to manually cancel subscriptions — see Cancel subscription.
• Use the UI to automate the cancellation of subscriptions, for example if a customer stops paying — see Stop subscriptions.

Edit subscription details

All subscription items can be edited or updated. For more information, select from the following:

• Use the UI to edit a subscription details — Edit a subscription.
• Use the API to edit a subscription details — Change order items.

Configure automatic cancellation of delinquent subscriptions

Use this process to configure the automatic cancellation of a pending subscription if it is not paid within a specified length of time.

The delinquency period is the length of time, in ISO-8601 durations format, before which a subscription with an invoice in past the due state is automatically canceled. If the provided value is null, the subscription does not change state.

Choose from the following options to set the delinquencyPeriod:

• To explicitly set the delinquency period when creating a subscription, use the delinquencyPeriod parameter.
• To deactivate the delinquency period, pass a null value in the delinquencyPeriod parameter.
• To calculate the time remaining in the delinquency period of a subscription, use the createdTime and the delinquencyPeriod parameters.

Related resources

• Orders API operations
• Invoices API operations