Credit Note Changes and Deprecations

Announcements
1

Hello everyone, :wave:

This is an important message that all API users should read.

As part of a wider effort at FreeAgent to improve and standardise Credit Notes in the product, we’re making some changes, which will affect all API users who interact with Invoices or Credit Notes via the API.

To fully understand these changes, you’ll need a quick introduction to how we currently store Credit Notes in the FreeAgent app, and some terminology to help the explanation of what is changing:

  • Credit Notes: Created using the “Convert to Credit Note” button (introduced in 2016), or those created using the more recently added “Add New Credit Note” button.

    • These items have not historically been accessible via the API, and don’t have their own endpoints

  • Negative Invoices: Credit Notes created from the “Add new Invoice” button, as you would create any other Invoice, or created via posting to the /v2/invoices endpoint, and which have a negative total value, due to negative line items being added.

    • These are currently accessible via the Invoices endpoints

As it stands there should not be a functional difference between the two in the product, since we added the “Add new Credit Note” button into the app at the end of last year.

The API Changes:

From today:

  • Credit Notes will be accessible via the API from newly created endpoints
  • It will not be possible to mark a Negative Invoice as sent via the web interface. This will still be possible via API calls until the end of the deprecation period.

After a 3 month deprecation period:

  • It will not be possible to transition a Negative Invoice to sent via the API.
  • Negative Invoices will be migrated to become Credit Notes, meaning that instead of being accessible via the invoices endpoints, they will be accessible via the credit notes endpoints

As API users, from today:

  • You’ll need to stop creating negative invoices (from /v2/invoices), and instead create a credit note (via /v2/credit_notes)
  • Be prepared for existing invoices, currently accessible via /v2/invoices to be migrated, and become accessible via /v2/credit_notes.

If you have any questions or concerns regarding this deprecation, or the new Credit Note endpoints, please do let us know as soon as you can by replying to this post. We’ll be monitoring this thread for any questions or feedback you may have, and will do our best to get back to you as soon as we can.
Also, if you think you’ll need assistance, or specific help ahead of the migration, please do let us know.

These changes will not take place before 4th May 2020.

We realise that some users will need to make changes to your integrations but we hope that these changes, once completed will allow you to interact with Credit Notes via the API in a consistent way, and will also allow us at FreeAgent to deliver some exciting improvements to Credit Notes later in the year.

All the best,
Peter Singh
Software Engineer at FreeAgent

Posted: 4th February 2020

3

Hi everyone,

We’ve now implemented the changes to Credit Notes and Negative Invoices as outlined in this post.

This means that from today:

  • It will not be possible to transition a Negative Invoice to sent via the API, aligning with the in-app behavior.
  • You can no longer create Negative Invoices (via /v2/invoices), and instead must create a Credit Note (via /v2/credit_notes)
  • Negative Invoices have been migrated to become Credit Notes, meaning that instead of being accessible via the invoices endpoints (/v2/invoices), they are accessible via the credit notes endpoints (/v2/credit_notes)

If you have any questions or concerns regarding this change, or the new Credit Note endpoints, please do let us know.

All the best,
Peter