Get invoices for a customer
Use this workflow to get invoices for a Customer.
This is typically used when an external system needs to display invoice history, payment status, due dates, invoice amounts, or links to invoice PDFs.
Endpoint
Code
Where {customerGuid} is the UtilityCloud GUID of the Customer.
When to use
Use this workflow when an external system needs to retrieve invoices for a specific customer.
Typical use cases include:
- showing invoice history in a customer portal
- displaying invoice status in a CRM or customer support system
- checking whether an invoice is paid, partly paid, reminded, or sent to debt collection
- retrieving invoice metadata before fetching invoice details or invoice PDF
- synchronizing invoice information to an external system
Query parameters
| Parameter | Description |
|---|---|
page | Page number used to retrieve invoices from the ERP system. Some ERP systems support paging based on invoice age. Use -1 to retrieve all invoices where supported. |
removeCredited | Indicates whether credited invoices should be removed from the result. |
Example request
Code
Paging
Some ERP systems support paging of invoices. A page contains invoices for a configured number of months, depending on the ERP system.
If the ERP uses two months per page, the paging behavior is typically:
| Page | Description |
|---|---|
-1 | Get all invoices |
0 | Get invoices for the last 2 months |
1 | Get invoices that are 2–4 months old |
2 | Get invoices that are 4–6 months old |
Response
The response contains invoice information for the customer.
Example structure:
Code
Response fields
| Field | Description |
|---|---|
invoiceGuid | Invoice identifier. |
erpid | ERP identifier for the invoice. |
invoiceNumber | Invoice number. |
postPeriod | Posting period. |
invoiceDate | Date when the invoice was issued. |
kid | Payment reference. |
dueDate | Invoice due date. |
amount | Total invoice amount. |
restAmount | Remaining unpaid amount. |
status | Invoice status code. |
pdf | URL or reference to the invoice PDF, where available. |
pdfMethod | Method/path information used to retrieve the invoice PDF. |
type | Invoice type. |
distributionChannel | Distribution channel used for the invoice. |
distributionDate | Date when the invoice was distributed, where available. |
directDebit | Indicates whether direct debit is used. |
yourReference | Customer or invoice reference, where available. |
paymentAgreement | Payment agreement information, where available. |
Invoice statuses
The following invoice status codes may be returned:
| Status | Description |
|---|---|
1 | In processing |
2 | Sent |
5 | Partly paid |
6 | Paid |
9 | Reminded |
10 | Dunning |
11 | Failed |
12 | Not to be sent |
15 | Lost |
16 | Lost with payment |
17 | Partly lost |
20 | Draft |
Notes
Invoices are retrieved from the ERP system.
Paging behavior depends on the ERP system and tenant configuration.
Use page=-1 to retrieve all invoices where this is supported.
Use the pdfMethod property of an invoice to construct the request for retrieving the invoice as PDF.
Use the invoice token together with invoice number or ERP id when retrieving invoice details or invoice PDF, depending on the endpoint used.
Related endpoints
Code