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.
Here is a big picture overview of the billing concepts.
|Customer||1 to many||Payment Instruments|
|Customer||0 to many||Orders|
|Order||1 to many||Invoices|
|Invoice||many to many||Transactions|
|Invoices & Orders||1 to many||Products and Plans (as "Items")|
|Product||1 to many||Plans|
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.
Just as the timing of the service period and billing may be different, so may the status of the service and the billing.
status represents the status of the service(s) of the subscription order (a one-time order has fewer possible statuses).
An order starts in a
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
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
|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.|
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.|
This is a billing resource and responsible for empowering many use cases.
The typical workflow involves creating an order (it will have a
Then collecting the payment against the invoice. That activates the order (sets the status to
active and sets the
You may find the details of the most recent invoice by referencing the
recentInvoiceId (or expanding the
recentInvoice within the API resource).
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.
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.
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 (
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.
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
If the invoice is very past due, it may be marked as
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
It's generally a bad idea to delete invoices, and considered illegal in some jurisdictions.
After an invoice is
paid, it may be
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.
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.
In other resources, the invoice id may be referred to as the
initialInvoiceId or something with "invoiceId" in the name.
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.
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.
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.