Orders

An order is a customer's request to purchase items. It can contain subscription and one-time sale items. When an order contains one or more subscription items, it is a subscription order. An order generates an invoice. A subscription order generates an invoice for each service period.

Service period anchor, billing timing, and invoice time shift

The following properties are used to configure subscription orders:

  • 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 order lifecyle

This section describes the subscription order lifecyle.

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

Order status

The order status describes the state of a subscription order. The following are all the order 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 order 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.
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 order and you, or the customer, choose not to activate it.
abandoned A pending order is not activated and the abandonTime is reached. The order is automatically marked as abandoned.

All status transitions

The following diagram describes all states of a subscription order.

Invoice is paid,
or payment instrument
is verified for free trial
Order not activated
and voided via API
Order not activated
and automatically abandoned
Trial-only period ended
Cancels subscription
Pauses subscription
Service period
completed
Paid service
period expired
Resumed
Reactivated
Reactivated
Pending
Active
Voided
Abandoned
Trial-ended
Canceled
Paused
Completed
Churned

Trial-only subscription

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

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

Paused subscription

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

Invoice is paid
Pauses subscription
Resumes subscription
1. Pending
2. Active
3. Paused
  1. A customer signs up to a subscription. 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 their subscription. The order is assigned the paused status.
  4. The customer resumes their subscription, or the pause end date is reached and the subscription automatically resumes. The order is assigned the active status.

Canceled subscription

This section describes the service states of a canceled subscription order.

Invoice is paid
Paid service period expired
Cancels subscription
Reactivates subscription
Reactivated
1. Pending
2. Active
3. Canceled
4. Churned
  1. A customer signs up to a subscription. The order is assigned the pending status.
  2. The customer pays the first invoice. The order is assigned the active status.
  3. The customer decides to cancel their subscription. The order is assigned the canceled status. The order 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 order.
  4. The time remaining on the last paid subscription period expires. The order is assigned the churned status. The customer is no longer subscribed to the service but can still reactivate the subscription.

Abandoned order

This section describes the service states of an abandoned order.

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

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

Completed subscription

This section describes the service states of a completed subscription order.

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

Billing status

The billingStatus represents the status of the most recent invoice.

BillingStatus Description When your application receives this billingStatus:
unpaid Invoice is issued to the customer. It is not paid. The payment time-frame has not exceeded. Email the invoice to the customer, see Automate emailing invoices. If autopay is turned off, Collect a payment.
past-due Invoice is issued to the customer. It is not paid. The payment time-frame has exceeded by more than 24 hours. Send a past due invoice reminder. Let the customer know they have a past due invoice with in-app messaging. Depending on your service costs, you may want to remove access and delivery.
abandoned An invoice is not paid, or not paid in full, and has been abandoned by the customer. Remove service access and delivery.
paid Invoice is paid by the customer. Grant service access and delivery. Send an invoice email confirmation; see Send a paid invoice notification.
partially-paid Invoice amount is partially paid by the customer Attempt to collect the remaining balance using email outreach.
voided Invoice amount is set to zero. Voiding retains the invoice number and lists it in reports but changes the amounts to zero. Remove service access and delivery, if it was granted.
disputed Invoice amount paid is disputed by the customer or merchant Remove service access and delivery.
refunded Invoice amount is fully refunded to the customer. Remove service access and delivery, if appropriate.
partially-refunded Invoice amount is partially refunded to the customer. No action required.

One-time orders

A one-time order is a single, non-recurring, amount that a merchant charges a customer. A one-time order can contain multiple one-time items. A one-time order is an order that does not contain any subscription items.

One-time order example: A one time purchase of two bags of coffee.

Status
 Description
pending A customer requests one or more one-time sales items in an order.
completed The customer pays the order invoice.
canceled The customer cancels the order before paying.

The following describes the status transitions of a one-time order.

Invoice is paid
Order canceled
1. Pending
Complete
Canceled
  1. A customer requests one or more one-time sales items in an order. The order is assigned the pending status.
  2. The customer pays the order invoice. The order is assigned the complete status.
  3. The customer cancels the order before paying. The order is assigned the canceled status.

Order form

Use order forms to collect payment for an order. Rebilly provides hosted payment forms, hosted checkout forms, and also Billing portals. To create your own form, see Choose an integration.

Order forms create an invoice for payment. When an order is created it has the pending status. When you collect the payment against the invoice, the order status is set to active and the activationTime property is also set.

To find information on the most recent invoice:

Expand resources

Some Rebilly API resources support the use of a query string parameter named expand. This parameter is used to request that additional resources are returned in the _embedded property of the response. The expand property accepts a comma-separated list of objects. For more information, see Query and expand.

Subscription order renewals

Rebilly automates the scheduling and generation of renewal invoices. If autopay is enabled, 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.

Configure automatic abandonment of pending orders

Use this process to configure the automatic abandonment of pending orders. An order is abandoned when it is created but not activated before the abandon time is reached. When an order is abandoned all associated invoices are voided.

note

Only pending orders can be abandoned.

Choose from the following options to set the abandonTime:

  • To explicitly set the date and time, the order must be abandoned, when creating an order use the abandonTime parameter .
  • To disable automatic abandonment, pass a null value in the abandonTime parameter .
  • To calculate the abandonTime automatically based on the time it was created ( createdTime ) and the TTL of the pending order ( organization.settings.billing.pendingOrderTTL ), do not send the abandonTime parameter.

Cancel a subscription order

Select from the following cancellation options:

Edit subscription order details

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