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. |
|
Phone number |
The phone number will be displayed in Chaser so that phone calls can be made easily by Chaser users. |
|
Mobile number |
The mobile number will be displayed in Chaser and can be easily viewed by Chaser users when they are required to call the customer. The mobile number will also be used to send an SMS, if you enable this on your account. The mobile number must include the country code e.g. +447261928377 |
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.