How to use Chaser API

This article provides an explanation of the data that can be passed to the Chaser API. This document will also explain how to push key updates (such as a payment on an invoice) so that it is correctly represented within Chaser.

Resources

The Chaser API has 4 resources: Customers, Invoices, Credit Notes, and Organisations.

Customers

The Chaser API allows you to interact with (GET, POST ,PUT) information relating to the organisations' customers.

Field Name

Description

ExternalID

This is the external (source system) ID for the customer. This must be unique for each customer.

Company Name

This is the name of the Company Name for the customer which we will be displayed in Chaser (and used in Monthly Statements and email templates if the relevant placeholder is selected)

Contact First Name

This is the first name of the recipient who will receive the reminders from Chaser

Contact Last Name

This is the last name of the recipient who will receive the reminders from Chaser

Contact Email Address

This is the email address that will receive the reminders sent using Chaser.

Status

The status dictates whether the Customer will be visible within Chaser. A Customer can either be ACTIVE, which means that they will be visible in Chaser, or ACHIEVED meaning that they will not be visible in Chaser.


Invoices


The Chaser API allows you to interact with (GET, POST ,PUT) information relating to the organisations' invoices.

For following fields are available:

Field Name

Description

Invoice ID

The Invoice ID will not be visible within Chaser but will be used to make future updates to the invoice. This ID should be unique for each invoice.

Invoice Number

The invoice number will be visually represented to represent the invoice in Chaser. In your reminder emails, this is the reference that will be shared with customers. In contrast to the above, this reference is not required to be unique.

Status

The status dictates whether the Invoice will be visible within Chaser.


- AUTHORISED = The invoice will be visible in Chaser

- PAID = The invoice will be visible in Chaser (under the "paid" filter in the receivables section) for a period of 6 months after the fully paid date. After this, it will be archived from Chaser's database.

- DRAFT, SUBMITTED, VOIDED, DELETED = The invoice will not be visible in Chaser, no reminders will be sent and the invoice will not be considered in any of Chaser's reporting

Currency Code

The currency code for the currency that the invoices are issued for. Please refer to ISO codes https://www.xe.com/iso4217.php

Amount Due

This should reflect the amount left to pay on the invoice after any partial payments or credits.

If no payments or credits have been applied to the invoice, this should reflect the total invoice value.

Amount Paid

This amount should reflect any payments that have been made or credits that have been applied to the invoice

Total

The total amount of the invoice

Date

The date that the invoice was raised

Due Date

The date that the invoice payment is due

Fully paid date

The date that the final payment on the invoice was made

Customer external ID

The external ID of the customer that the invoice should be associated with

 

How do I mark an invoice as paid?

When adding invoices, it is important to ensure that the relevant customer has been created in Chaser first (using the POST add customer call). The external customer ID will be used to associate the invoice with the correct customer. If the Customer does not exist, the API will return an error.

Note: A valid customer ID is required to create an invoice, therefore the customer must be created using the POST add customer endpoint prior to adding the invoice. The customer external ID is used to match an invoice with a customer's

 

Credit notes

Chaser’s monthly statements will include any credit notes if they meet the following criteria (they are ACTIVE and remaining credit). The monthly statement sent by Chaser will calculate the overall customer balance by subtracting unallocated credits from invoice amounts.

The Chaser API allows you to interact with (GET, POST ,PUT) information relating to the organisations' credit notes.

 

Field name

Description

Credit note id

The Credit note id will not be visible within Chaser but will be used to make future updates to the credit notes. This ID should be unique for each credit note.

Credit note number

The Credit note number will be visible on Monthly Statements that are sent to customer.

Remaining credit

The remaining (unallocated) credit left on the credit note.

Date

The date that the credit note was issued.

Status

The status of the credit note dictates whether it will appear on the customer statement. If a credit note is ACTIVE, it will appear. If a credit note is SUBMITTED, AUTHORISED, PAID, VOIDED or DELETED, it will no longer be visible.

Total

The total amount of the credit note.

Currency

The currency that the credit note has been raised in.

Customer external id

The external ID of the customer that the credit note should be associated with.

 

When adding credit notes, it is important to ensure that the relevant customer has been created in Chaser first (using the POST add customer call). The external customer ID will be used to associate the credit note with the correct customer. If the Customer does not exist, the API will return an error.

Note: A valid customer ID is required to create an invoice, therefore the customer must be created using the POST add customer endpoint prior to adding the invoice. The customer external ID is used to match an invoice with a customer

 

FAQS

How do I mark an invoice as paid?

To mark an invoice as paid, the following fields should be updated using the ”update invoice by id” endpoint

  • Invoice Status is equal to PAID
  • Amount due = 0
  • Amount paid = The total amount of the invoice
  • Fully paid date = The date that the final invoice was paid

How do I apply a partial payment to an invoice?

To apply for a partial payment, the following fields should be updated using the ”update invoice by id” endpoint: 

  • Amount due = total - all payments applied
  • Amount paid = sum of all payments that have been applied to the invoice


As the invoice still have a remaining balance, the status should remain unchanged and the fully paid date should be null.

How do I apply a credit to an invoice?

In order to apply a credit to an invoice, you will be required to make updates to the related invoice and also the credit note that has been allocated.

Firstly to update the invoice, please follow the steps above which explain how to 1) How to mark an invoice as paid - if the credit pays the full remaining balance of the invoice 2) How to apply a partial payment - if the invoice will still have a balance remaining following the allocation of the credit

Secondly, the credit note will also need to be updated.

If the allocation of credit uses all remaining credit on the credit note, the following fields should be updated:

  • Status = PAID
  • Remaining credit = 0


If after allocating the credit, the credit note still has a balance remaining, only the below field updates are required:

  • Remaining credit = total credit minus the sum of all balances that have been allocated to invoices

No status update is required when only part of the credit note is applied.


What date formats are acceptable?


Chaser API requires that all dates use the ISO format (ISO 8601) YYYY-MM-DDTHH:mm:ss.sssZ.