An invoice represents an amount owed by an account to an organization for some service provided.
Invoices are automatically generated on billing events, for example when at the end of a subscription’s billing cycle or for a intra-contract upgrade. Invoices contains a breakdown of line items for each charge, the tax calculation applied and any discount.
Types
An invoice may be of three potential types. The types of invoice affect the result of an invoice not being paid or reason it was generated:
- Adhoc An invoice resulting from an Adhoc subscription. Adhoc subscriptions only issue a single invoice. These are used for one-off payments
- Subscription An invoice resulting from a recurring or non-recurring subscription.
- Amendment An invoice resulting from an intra-contract upgrade to a subscription.
The platform generates an invoice from a subscription definition and as such an organization will never directly create an invoice. If an invoice is either Adhoc or Amendment then only a single execution attempt will be taken. In the case of an Adhoc invoice a failure to pay the execution on this attempt will result in the subscription being marked as failed. In the case of an Amendment invoice a failure to pay the invoice will have no affect on the subscription other than the upgrade failing.
A subscription invoice will attempt to be executed as long as their are sufficient dunning lines associated with the invoice. An invoice may be re-executed at any point, it is worth noting that each execution counts as a dunning attempt. Once an invoice has reached the total execution attempts allowed by dunning it will no longer attempt to be paid, and will remain in the unpaid state. A manual execution attempt may be taken to pay the invoice at any point.
States
An invoice has three potential states associated with it:
- Pending A pending invoice is one which has been generated but has not yet been issued to a customer. When an invoice is in this state it’s cost may be altered. For example subscriptions with usage based billing will enter a pending state if the usage has not been set. A pending invoice can be re-generated with any cost alterations applied.
- Unpaid An unpaid invoice is one which has been issued to a customer and is awaiting payment. An unpaid invoice will be scheduled for automatic payment execution attempts based on an organizations dunning configuration.
- Paid A paid invoice is one which has been issued and successfully paid.
Value
An invoice is composed of a number of invoice lines. Each invoice line represents a calculation from a pricing-component as defined in the Product Rate Plan. The sum of all these invoice lines results in the invoiceCost . In certain situations an invoice may become paid with the total revenue paid being different from the invoice cost. The invoicePaid value is the total cash receive for this invoice and as such represents revenue. An example of when an invoiceCost may differ from an invoiceValue is when an invoice is partially paid for by a coupon or credit. An invoice is paid for using a collection of invoicePayments. Please see Payments and Invoice Payments for further information.
Period Start
In the case of a subscription invoice the invoice covers a service period. The service period is starts from the periodStart till the periodEnd .
Taxation
Dependent on the Taxation Strategies defined for the product rate plan a tax amount is automatically calculated for an invoice.