Subscriptions

A subscription is a recurring item in an order. It is a 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.

A subscription item is active while the order that contains it is active. Pause, cancel, and reactivate apply to the order, and every subscription item in that order follows the change. A single subscription item cannot be paused, canceled, or reactivated on its own.

The statuses in this section describe an order that contains subscription items. A subscription item has no status.

Example: A monthly order for an internet service that is charged at 20 USD per month.

status describes the state of the order. The following are all statuses.

The following diagram describes all states of an order that contains subscription items.

This section describes the status of a trial-only order that contains a subscription item.

1. A customer signs up for a trial-only order that contains a subscription item. The order is pending.
2. The customer verifies a payment instrument, the customer's payment instrument is charged, or the order startTime is exceeded. The order is active.
3. The trial period of the order ends. The order is trial-ended. When the trial ends, the customer can continue the subscription item with recurring billing or stop using the product.

To convert a trial-ended trial-only order that contains a subscription item to recurring billing without restarting the trial, create a change quote. When the quote is accepted, the order that contains the subscription item is active and recurring billing begins. For more information, see Quotes.

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

1. A customer signs up for an order that contains subscription items. The order is assigned the pending status.
2. The customer pays the first invoice. The order is assigned the active status.
3. The customer pauses the order. The order is assigned the paused status. Every subscription item in the order is paused.
4. The customer resumes the order, or the pause end date is reached and the order resumes. The order is assigned the active status.

This section describes the states of a canceled order.

1. A customer signs up for an order that contains subscription items. The order is assigned the pending status.
2. The customer pays the first invoice. The order is assigned the active status.
3. The customer cancels the order. The order is assigned the canceled status. The order keeps this status until the time remaining on the last paid service period expires. The customer is still subscribed to the service and can reactivate the order.
4. The time remaining on the last paid service period expires. The order is assigned the churned status. The customer is no longer subscribed to the service, but can still reactivate the order.

This section describes the states of an abandoned order.

Use the abandoned status to differentiate between an order that is voided and a pending order that is abandoned because it is not activated.

1. A customer signs up for an order that contains subscription items. The order is assigned the pending status.
2. The order is assigned an abandonTime value when the order is created, or from the organization billing settings.
3. The abandon time is reached, and the order is assigned the abandoned status. Associated invoices are voided.

This section describes the states of a completed order.

1. A customer signs up for an order that contains subscription items. The order is assigned the pending status.
2. The customer pays the first invoice. The order is assigned the active status.
3. The service period of the order is concluded. The order is assigned the completed status. From this state, the customer can begin a new order.

This section describes how to manage subscriptions.

For more information on the UI, see Manage billing.

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.

If subscription items are changed, the recurring interval and service period anchor are updated based on the new item plans.

To keep a trial-only order in trial-only, set the renewal policy to retainTrialOnly.

If the renewal policy is retainTrialOnly or retainTrialThenRecurring, the new items keep the trial end time of the order. The trial ends when the renewal policy is resetToRecurring or retainRecurring.

If the order specifies a trial end time and is not in trial, the new items use the specified trial end time. If no trial end time is specified for the order, the new items use the trial period from the plan.

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 order, or when invoices get paid, see Webhooks.

Alternatively, use the UI to send email notifications. Create event-based email notifications using the invoice paid and order activated events.

Canceling an order cancels every subscription item in that order.

Select from the following cancellation options:

• Use the API to cancel an order — see Cancel an order.
• Use the UI to manually cancel an order — see Cancel order.

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

• Use the UI to edit subscription items or settings — Modify subscription items or settings.
• Use the API to change order items — Change order items.

Use this process to configure the automatic cancellation of an order that contains subscription items if it is not paid within a specified length of time.

The delinquency period is the length of time after which an order with a past-due invoice is automatically canceled. The value uses the ISO 8601 duration format. Example: P30D for 30 days. Delinquency time is calculated for each invoice using the invoice due time and the delinquency period of the order.

Use the following options to manage delinquency periods:

• When creating an order:

  • Set the delinquency period using the delinquencyPeriod parameter and the create an order API operation.
  • Deactivate the delinquency period by passing a null value in the delinquencyPeriod parameter and the create an order API operation.

• When updating an active order:

  • Set the delinquency period using the delinquencyPeriod parameter and the upsert an order API operation.

    If you add a delinquency period to an active order, it is applied to all new invoices created for the order. It is not applied to the unpaid and past-due invoices.

  • To apply a delinquency period to unpaid invoices, set the delinquencyTime to the current time plus your desired delinquency period. For more information, see the delinquencyTime parameter in the upsert invoice API operation.

• Orders API operations
• Invoices API operations