Last updated
These docs are intended for a developer audience.Dismiss

Invoices

An invoice is a bill for a list of goods and services provided. If your invoice includes subscription items, it also includes the corresponding service periods and prices.

Invoice components

An invoice is sent from a merchant's organization to a customer. The customer may have a billing address and delivery address. Invoices are sequentially numbered for each customer. If an invoice is associated with a subscription, the subscriptionId value is displayed. Invoices contain line items. Each line item may have a product ID, plan ID, quantity, service period and pricing information.

An invoice may have associated coupons & discounts, shipping, taxes, transactions, and credit memos.

Invoice lifecycle

This section describes the invoice lifecycle and related terms.

Deleting invoices is not recommended, it may also be illegal in some jurisdictions.

Invoice status

The following are all invoice status types.

Status
Description
abandonedInvoice is not paid, or not paid in full, and has been abandoned by the merchant.
paidInvoice is paid by the customer.
partially-paidInvoice amount is partially paid by the customer.
partially-refundedInvoice amount is partially refunded to the customer.
past-dueInvoice is issued to the customer. It is not paid. The payment time-frame has exceeded by more than 24 hours.
refundedInvoice amount is fully refunded to the customer.
unpaidInvoice is issued to the customer. It is not paid. The payment time-frame has not exceeded.
voidedInvoice amount is set to zero. Voiding retains the invoice number and lists it in reports but changes the amounts to zero.
disputedInvoice amount paid is disputed by the customer or merchant.
draftInvoice that is not issued yet.

Invoice issued and paid on or by due date

This section describes the invoice lifecycle for an invoice that is paid on or by the due date.

Full payment
1. Invoice issued
2. Invoice paid in full
  1. An upcoming invoice is issued and assigned the unpaid status.
  2. The invoice is paid in full and assigned the paid status.

When an invoice is paid, it may be refunded or disputed. If an invoice is disputed, you may want to suspend the subscription service until the dispute is resolved. For more information, see Pause subscriptions or the Pause a subscription operation.

Invoice issued and partially paid

This section describes the invoice lifecycle for an invoice that is partially paid.

Partial payment
Remaining balance paid
Amount refunded
Amount refunded
Amount refunded
1. Invoice issued
2. Partially paid
Paid
Refunded
Partially refunded
  1. An upcoming invoice is issued and assigned the unpaid status.

  2. The invoice is partially paid and is assigned the partially-paid status. From the partially-paid state:

    • If the customer pays the remaining amount, the invoice is assigned the paid status. This amount can be partially-refunded, or fully refunded.
    • If the customer does not pay the remaining amount, the partially paid amount can be partially-refunded, or fully refunded.

Invoice issued and not paid

This section describes the invoice lifecycle for an invoice that is not paid.

No payment
24 hours after due time
Reissued
Reissued
Reissued
1. Invoice issued
2. Unpaid
Past Due
Abandoned
  1. An upcoming invoice is issued and assigned the unpaid status.
  2. The invoice is not paid on or before the due date, it retains the unpaid status for 24 hours.
  3. The invoice exceeds the 24 hour time-frame. The invoice is assigned the past-due status.
  4. The invoice is not paid within the past-due time-frame.
  5. The merchant decides to abandon the collection of payment. Or, the autopay retry attempt limit is exceeded. The invoice is assigned the abandoned status.

Usage

If you follow the suggested order workflow, you may utilize the invoice using the expand=recentInvoice query string parameter and value on the order API requests. You may also retrieve any invoice by its ID, for example: GET invoices/123.

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

Webhooks

Use webhooks to notify your systems when certain events occur, and to collect information about the events. For more information, see Webhooks.

To record paid invoices in your own system, or push the data to third parties, create a trigger on the Invoice paid event.

Rebilly also provides custom webhooks, that enable you to control the payload using placeholders. These may be useful for integrating directly to third parties without needing to mediate the requests and responses.

Automate emailing invoices

Use Rebilly to email invoices to your customers. For more information, see Automate emailing invoices.

Taxes

Rebilly supports automated tax calculations internationally, using the location of your organization and the location of your customer. You may also manually adjust the taxes on an unpaid invoice. Rebilly calculates taxes after an invoice is issued and recalculates them on every invoice change. The shipping amount is added to tax calculations. For more information, see Taxes.

To calculate taxes:

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

If you would like to use third-party tax calculators, Contact us.

Coupons and discounts

For information on coupons and discounts, see Coupons and discounts and the Coupons operations.