FreeAgent API — invoice reference and global sequencing

1

I’m integrating with the FreeAgent API to create daily sales invoices via the Invoices endpoint. I have two questions:

How does the built-in Amazon integration create invoices with a reference like “Amazon Sales 2026-05-22” without it bumping the user’s global invoice sequence? Does the internal integration use a different mechanism than the public API?

When creating an invoice via the public API with a reference field set to a non-numeric string (e.g., “Sales 2026-05-27”), will FreeAgent’s global sequence counter attempt to increment from that value? Or does the counter only follow numeric/auto-sequenced references?

I’m trying to understand whether there’s a way to set a custom reference on an invoice via the API without disturbing the user’s own invoice numbering.

Thanks

2

Hello,

FreeAgent’s built-in Amazon integration makes use of contact-level sequencing for the contact(s) that it creates. You can read more about the different types of sequencing available in FreeAgent in this knowledge base article.

When FreeAgent generates a reference for a new invoice, it will look for the latest existing invoice associated with the appropriate sequencing level (in order: recurring invoice profile, project, contact, global), and try and increment the reference from there:

INV123    -> INV124
Q1 INV123 -> Q1 INV124
MYREF     -> MYREF001

So while it isn’t possible to prevent an invoice’s reference influencing future reference generation entirely, the use of a contact with contact-level sequencing or a project with project-level sequencing can contain the influence to just those levels’ invoices.

Kind regards,
Josh
FreeAgent engineering