Eventsforce has an API that allows external applications to access and update information, including invoices and payments.
We would recommend that integrators start by reading our API documentation, and then read this section for some additional hints and tips that might be useful for finance integrations.
Invoices and credit notes
The API lists all invoices and credit notes together in the “invoices” resource - credit notes have a negative total and a type of “credit note”.
Getting the latest invoice for a registration
Each registration can have multiple invoices and credit notes. The invoices are related using the properties “nextRelatedInvoiceNumber” and “previousRelatedInvoiceNumber”.
Typically finance systems will want to pull all invoices and credit notes for each registration so they have a complete history for that account. If you just want the latest invoice however then you can find this by looking at “nextRelatedInvoiceNumber” - if this is null then this invoice is the latest invoice (or credit note) for this registration.
Getting new invoices each day
A common requirement is to get new invoices from Eventsforce as a batch job each day, and link them to a finance system (example: to send the invoices to customers).
This pseudocode may be helpful to do this:
lastInvoiceNumber = 0
repeat forever
{
get all the invoices > lastInvoiceNumber using
/api/v2/invoices.json?invoiceNumberAfter=lastInvoiceNumber
for each invoice
{
get the invoice details
if externalInvoiceReference is blank (i.e. we've not dealt with it yet)
{
add the invoice to the finance system
update externalInvoiceReference in Eventsforce with
the finance system invoice number
lastInvoiceNumber = invoiceNo
}
}
sleep for 24 hours
}
Getting new invoices based on event data
Another common requirement is for a finance system to get new invoices from Eventsforce when the event manager has marked the event as “ready”. To do this we can use custom event fields.
A “custom event field” is data that is held against an event - this is defined by the system administrator, and can be any type of data that Eventsforce supports. This could be used to add a checkbox called “Release all invoices” for instance.
This updated pseudocode may be helpful to do this:
lastInvoiceNumber = 0
repeat forever
{
get all the invoices > lastInvoiceNumber using
/api/v2/invoices.json?invoiceNumberAfter=lastInvoiceNumber
firstNewInvoice = 0
for each invoice
{
get the invoice details
if externalInvoiceReference is blank (i.e. we've not dealt with it yet)
{
get custom event fields from the event
if “ready for invoice” custom event field is checked for this event
{
add the invoice to the finance system
update externalInvoiceReference in Eventsforce with
the finance system invoice number
}
else
{
// We’ve decided not to fetch this invoice yet. If it is
// the first new one then remember where to start next time.
if firstNewInvoice is 0
{
firstNewInvoice = invoiceNo
}
}
}
}
// Remember where to start next time
if firstNewInvoice <> 0
{
lastInvoiceNumber = firstNewInvoice - 1
}
sleep for 24 hours
}
This pseudocode above could be adapted to check any combination of custom event data or other data to make a decision. The API makes it easy to navigate from an invoice to the event using “eventDetailsURL”.
Getting new invoices marked as “printed”
An event manager may want to “release” invoices to the finance system after a manual vetting process. Eventsforce supports this through a flag on the invoice called “markedAsPrinted”.
In the admin portal, an event manager can choose Financial Management > Invoice Run and “Print” the invoices. This will set “markedAsPrinted” for those invoices to true.
An external finance system can then check the “markedAsPrinted” flag when deciding whether to pull invoices or not.
Posting a payment against a registration
In the API, payments are posted against an invoice rather than a registration. For clarity we would recommend that payments are posted against the latest invoice, however in practice the payment can be posted against any invoice for the registration - Eventsforce will sum all the payments and refunds.
Posting a refund against a registration
When a refund is made to a registration contact, Eventsforce must be updated with the refund amount. To do this using the API, post a negative payment against any invoice or credit note related to the registration.
Note: Eventsforce cannot currently make refunds to cards, this must be done manually (example: using the payment gateway software) and updated in Eventsforce.