Last updated 3 minutes ago

Orders (fka Subscriptions)

An Order is summarized as a request by a customer to purchase some items.

It may be a one-time order or a subscription order.

Because "subscription one-time order" is an oxymoron, we're transitioning our language to describe this concept as an order. Be aware that we may use the term order and subscription interchangeably. Also, the API operations have "subscriptions" in the path.

An order's main purpose is to create an invoice (or invoices). Read more about invoices (the next core concept), after you read this page.

Service and Billing Anchors

A subscription order has a service period anchor and a billing anchor. The service period anchor is used, in conjunction with the start time, to calculate the concrete service period.

The billing period anchor is used to determine when, relative to the service period date, is the invoice issued. The billing timing controls whether or not the service is prepaid in advance or postpaid in arrears. However, the billing period anchor determines if there is a time shift between the changing of service periods.

In most scenarios, the service period is aligned with the billing period. For example, the period ends on the 1st of the month, and is billed on the 1st of the month.

In other cases, the billing may be before or after that service period changes. For instance, our AWS service period ends on the 1st, but the invoice isn't issued until the 3rd of the month. We call that a billing time shift. We pay AWS postpaid for most services, with a billing time shift of 3 days after the period change.

Status Lifecycles

Just as the timing of the service period and billing may be different, so may the status of the service and the billing.

Service Status

The status represents the status of the service(s) of the subscription order (a one-time order has fewer possible statuses).

  • pending
  • active
  • canceled
  • churned
  • paused
  • abandoned

An order starts in a pending status.

When it is activated, it will be in an active status. That may commonly happen when the initial invoice is paid.

For a free trial, it may happen upon payment instrument verification.

If it is a subscription order, it may be canceled, churned, or paused.

When a subscription order is canceled the customer may still have service period they paid for remaining.

When a subscription order is churned it means the customer does not have any service period remaining.

If you have a service, remove access when the status is churned (not canceled).

When the status value becomes... You should consider these actions...
pending - Show a preview of invoice (with shipping, discounts, and taxes calculated).
- Completing the payment of the invoice.
active - Grant access to your service.
- Trigger onboarding campaign.
canceled - Trigger offboarding or retention campaign.
churned - Remove service access and delivery.
- Trigger winback campaign, conditionally based on the reason.
paused - Trigger "resume" campaign.
- Remove service access and delivery.
abandoned - Trigger "recover cart" campaign.

Billing Status

The billingStatus represents the status of the most recent invoice.

It mirrors the statuses of the invoices, which you may read more about on the next page.

When the billingStatus value becomes... You should consider these actions...
unpaid - Emailing the invoice to your customer (Rebilly can do that for you).
- Completing the payment of the invoice (if autopay is off).
past-due - Sending a past due email notice for renewals (Rebilly can do that for you).
- Letting the customer know they have a past due invoice with in-app messaging.
- Depending on your service costs, you may wish to remove access and delivery.
delinquent - Remove service access and delivery.
paid - Grant service access and delivery.
- Send paid invoice email confirmation.
voided - Remove service access and delivery, if it was granted.
disputed - Remove service access and delivery.
refunded - Remove service access and delivery, if appropriate.

Usage

This is a core resource and responsible for empowering many use cases.

Order Form

The typical workflow involves creating an order (it will have a pending status).

Then collecting the payment against the invoice. That activates the order (sets the status to active and sets the activationTime property).

You may find the details of the most recent invoice by referencing the recentInvoiceId (or expanding the recentInvoice within the API resource).

Expand Resources

Some of our API resources supports the usage of a query string parameter named expand which accepts values that cause the API to return additional resources inside of the _embedded property of the response.

PUT subscriptions/my-test-123?expand=recentInvoice

Important tip: the value recentInvoice is case sensitive.

Subscription Order Renewals

Rebilly automates the scheduling and generation of renewal invoices. If autopay is true, then Rebilly also schedules payment against the invoices automatically.

To stay informed on changes to the subscription, or when invoices get paid, subscribe to webhooks.

Canceling a Subscription Order

You can cancel a subscription order, but sometimes Rebilly may cancel a subscription order too based on how you configure rules and automations.

Changing a Subscription Order

You can change subscription orders.

Updating Address info

Updating billing or delivery address info.

Adding Items (upsells)

Add items (one-time or subscription items). Subscription items must all have the same recurring length within the same subscription.

Removing Items

You can remove items.

Changing Service and Billing Anchor

You can change the service period and the billing anchor.