Early Invoicing

Overview

Typically the invoicing system is triggered by the generateTime on installments are billable. Once this trigger is reached, the system will gather all installments for the account that have reached their generate time, and create one or more invoices from them.

“Early” invoicing involves issuing invoices for installments that haven’t yet reached their generate time.

Invocation

Early invoicing starts with a request to the Initiate Early Invoicing endpoint. The EarlyInvoicingRequest contains information used to determine which uninvoiced installments will be invoiced. This can be done either by:

  • Specifying an accountLocator and the invoiceThroughTime, which will identify all installments that are uninvoiced and have a generateTime at or before the given time; or by

  • Specifying a set of installments using the installmentLocators property.

In addition, you can include:

  • An optional invoiceDueTime, which if provided will

  • An optional timezone, which if provided will override the system-calculated timezone

  • The ignoreHolds flag, which if set to true will exclude all installments for accounts that have an invoicing hold set.

Note

If no installments are found based on the request, then no invoices will be created and no error will be generated.

Behavior

The system will gather all the installments to be invoiced (either explicitly, or based on the generate time) and then group them as needed based on billing level and currency. They will not be grouped separately based on different due times, start or end times, timezones, etc.

For each installment group, one invoice will be created:

  • The dueTime for the invoice will be either the dueTime specified in the request, or if that is not set, the earliest dueTime of all the installments in that group.

  • The startTime will be the earliest startTime for all the installments in the group.

  • The endTime will be the latest endTime for all the installments in the group.

  • The timezone will be the timezone in the request, or if that is not set, the timezone of the installment with the earliest startTime.

Early invoicing is handled asynchronously from the request sent. The response object includes the jobLocator of the early invoicing job.

Error Conditions

An error will result in any of these cases:

  • The invoiceThroughTime is given without also including the accountLocator

  • The invoiceThroughTime and installmentLocators are both set, or neither set

  • The installmentLocators contain installments belonging to more than one account

Note

If an installment locator is given that is already invoiced, it will be ignored. Also, if the accountLocator is set, it will be ignored if invoiceThrough is not set.

Important

Up to 1000 installments per request are supported.

See Also