# 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.

| **Status**  | **Description** |
|  --- | --- |
| `pending` | A customer signs up to a subscription service. |
| `active` | A customer pays the first (initial) invoice for a new subscription, the subscription `startTime` is exceeded; or for a free trial, the customer's payment instrument is verified. |
| `canceled` | A customer cancels a subscription. To cancel a subscription, the subscription must be in an active or paused state. The subscription remains in the canceled state until the time remaining on the last paid subscription period expires, at which point the state changes to churned. |
| `churned` | The time remaining on the last paid subscription period expires. The customer is no longer subscribed to the service but can still reactivate the service. |
| `paused` | A customer pauses their subscription. Or, a merchant pauses a customer's subscription. |
| `completed` | Subscription service period is concluded. |
| `trial-ended` | A customer's trial period is ended. This status is exclusive to trial-only subscriptions. |
| `voided` | There is an issue with the subscription and you, or the customer, choose not to activate it. |
| `abandoned` | A pending subscription is not activated and the `abandonTime` is reached. The subscription is automatically marked as abandoned. |


### All subscription status transitions

The following diagram describes all states of a subscription.


```mermaid
graph LR;
    A(Pending) --> |Invoice is paid,<br/>or payment instrument<br/>is verified| B(Active)
    A(Pending) --> |subscription not activated<br/>and voided by API| Z(Voided)
    A(Pending) --> |subscription not activated<br/>and automatically abandoned| X(Abandoned)
    B --> |Trial-only period ended| C(Trial-ended)
    B --> |Cancels subscription| D(Canceled)
    B --> |Pauses subscription| E(Paused)
    B --> |Service period<br/>completed| F(Completed)
    D --> |Paid service<br/>period expired| G(Churned)
    E -.-> |Resumed| B
    D -.-> |Reactivated| B
    G -.-> |Reactivated| B
```

### Trial-only subscription

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


```mermaid
graph LR;
    A(1. Pending ) --> |Payment instrument<br/>is verified, or charged,<br/> for the trial.| B(2. Active)
    B --> |Trial is concluded| G(3. Trial ended)
```

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 [Subscription pauses](/docs/data-tables/manage-subscriptions#subscription-pauses) or the [Pause a subscription](/docs/dev-docs/api/orders/postsubscriptionpause/) API operation.


```mermaid
graph LR;
    A(1. Pending ) --> |Invoice is paid| B(2. Active)
    B --> |Pauses subscription| C(3. Paused)
    C -.-> |Resumes subscription| B
```

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.


```mermaid
graph LR;
    A(1. Pending ) --> |Invoice is paid| B(2. Active)
    D --> |Paid service period expired| C(4. Churned)
    B --> |Cancels subscription| D(3. Canceled)
    D -.-> |Reactivates subscription| B
    C -.-> |Reactivated| B
```

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.


```mermaid
graph LR;
    A(1. Pending ) --> |Invoice is paid| B(2. Active)
    B --> |Subscription service period is concluded| C(3. Completed)
```

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](/docs/data-tables/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](/docs/settings/products-and-pricing#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](/docs/dev-docs/webhooks-configuration).

Alternatively, use the UI to send email notificationss. [Create event-based email notifications](/docs/automations/email-notifications#create-event-based-email-notifications) using the invoice paid and subscription activated events.

### Cancel a subscription

Select from the following cancellation options:

- Use the API to cancel a subscription — see [Cancel an order](/docs/dev-docs/api/orders/putsubscriptioncancellation/).
- Use the UI to manually cancel subscriptions — see [Cancel subscription](/docs/data-tables/manage-subscriptions#cancel-a-subscription).


### 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 — [Modify subscription items or settings](/docs/data-tables/manage-subscriptions#modify-subscription-items-or-settings).
- Use the API to edit a subscription details — [Change order items](/docs/dev-docs/api/orders/postsubscriptionitemschange/).


### 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](/catalog/all/orders/postsubscription/#!t=response&c=201&path=0/delinquencyPeriod).
- To deactivate the delinquency period, pass a `null` value in the [`delinquencyPeriod` parameter](/catalog/all/orders/postsubscription/#!t=response&c=201&path=0/delinquencyPeriod).
- To calculate the time remaining in the delinquency period of a subscription, use the `createdTime` and the `delinquencyPeriod` parameters.


## Related resources

- [Orders API operations](/docs/dev-docs/api/orders/)
- [Invoices API operations](/docs/dev-docs/api/invoices/)