# 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

```http
GET /be/v3/invoice/{customerGuid}?page={page}&removeCredited={removeCredited}
```

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

```http
GET /be/v3/invoice/9c571be0-a689-4b83-9343-4043b5328836?page=-1&removeCredited=false
```

## 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:

```json
{
  "invoices": [
    {
      "invoiceGuid": "14370",
      "erpid": "14370",
      "invoiceNumber": "59123",
      "postPeriod": "032023",
      "invoiceDate": "2023-03-15T00:00:00+00:00",
      "kid": "005968601091955",
      "dueDate": "2023-03-29T00:00:00+00:00",
      "amount": 3825.63,
      "restAmount": 3825.63,
      "status": 1,
      "pdf": "https://...",
      "pdfMethod": "invoice?token=NzA4MDA...MTk=&number=59123&GLN=7080001234567",
      "type": "Invoiced",
      "distributionChannel": null,
      "distributionDate": "",
      "directDebit": false,
      "yourReference": "",
      "paymentAgreement": null
    }
  ]
}
```

## 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

```http
GET /be/v3/invoice/{customerGuid}
GET /be/v3/invoice/{customerGuid}/pdf?number={invoiceNumber}&token={token}
GET /be/v3/invoice/details?erpid={erpId}&token={token}
GET /be/v3/invoice/details?number={invoiceNumber}&token={token}
```