Billing concepts

In order to use our billing product, there are additional resources that are important to understand that work in conjunction with the core concepts.

First, review the relationship resources. Then, take some time to read about the billing concepts.

Resource relationships

Here is a big picture overview of the billing concepts.

Billing concepts

Orders

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.

An order's main purpose is to create an invoice (or invoices).

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.

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

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.

Usage

This is a billing 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 support 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

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.

• Update address info - change the billing or delivery address info.
• Add items (upsells) - Add items (one-time or subscription items). Subscription items must all have the same recurring length within the same subscription.
• Remove items - You can remove items.
• Change service and billing anchor - You can change the service period and the billing anchor.
• Change plans - You can change the plan associated with the order. You may choose the effective date and charge a prorated amount for the change.
• Change trial end date - You may want to extend the trial period for a customer. You may do so by changing the trial end date.
• Change quantity - You can change the quantity.

Invoices

An invoice is a bill for a list of goods and services provided.

If your invoice has subscription items on there, then it will also include the corresponding service periods and prices.

Components of the invoice

An invoice is from an Organization to a Customer. The Customer may have a billing address and delivery address.

An invoice is sequentially numbered for each Customer. This prevents any customer from reverse engineering how many other customers you may have, while still complying with the laws.

The invoice may be related to the order (subscriptionId).

An invoice has line items, and each line item may have a product id, plan id, quantity, service period and pricing information.

The invoice may have coupons & discounts, shipping and taxes information.

Status lifecycle

An invoice, when issued, may start as unpaid. Once paid, the status would change to paid. If it is not paid though, and it passes the due time, the status is marked as past-due.

If the invoice is very past due, it may be marked as delinquent.

The invoice could be marked as abandoned, when you give up on collection efforts.

If the invoice had some mistake on it, it may be marked as voided.

It's generally a bad idea to delete invoices, and considered illegal in some jurisdictions.

After an invoice is paid, it may be refunded or disputed.

This is important to know, because if an invoice is disputed, you may wish to suspend the subscription order service until the dispute is resolved.

Usage

If you follow our suggested order workflow, you may be utilizing the invoice via the expand=recentInvoice querystring parameter and value on the order API requests.

You may also retrieve any invoice by its id.

GET invoices/123

In other resources, the invoice id may be referred to as the invoiceId, recentInvoiceId, initialInvoiceId or something with "invoiceId" in the name.

Webhooks

The "invoice was paid" event is a useful event to subscribe to if you want to record paid invoices in your own system, or push the data to 3rd parties. Before pushing the data to 3rd parties, contact us to see if we're already integrated with the 3rd party.

Rebilly also has custom webhooks, where you can control the payload using placeholders. These may be useful for integrating directly to 3rd parties without having to mediate the requests and responses.

Emails

Invoices are commonly mailed to customers as pdf attachments.

It is easy to configure Rebilly to do that for you, without needing to do any integration yourself. Rebilly is integrated with 5 email service providers, making it easy for you to use your preferred provider, or you can use our "house" account.

Taxes

Rebilly is integrated with a 3rd party tax calculator (Tax Jar).

For taxes to be calculated, these conditions must be met:

• The product must be "taxable"
• The organization must have a full address
• The customer must have a full address

If you are interested in other 3rd party tax calculators, please contact us. Taxes may also be set manually.

Extending billing concepts

Coupons and discounts

You will likely configure coupons within the app.However, you can also configure coupons by API.