---
title: Manage Invoices
slug: manage-invoices
docTags: 
createdAt: 2026-02-13T04:24:48.354Z
---

# Manage Invoices

This guide provides comprehensive instructions for retrieving, updating, and deleting invoice data using the Nue API. 

## Retrieve Invoices

### REST Endpoints (Recommended)

Nue provides REST endpoints for retrieving invoices with flexible filtering, pagination, and data enrichment:

### 1. Global Invoice Listing

```http
GET https://api.nue.io/invoices
```

### 2. Customer-Scoped Invoices

```http
GET https://api.nue.io/customers/{customerId}/invoices
```

### 3. Individual Invoice

```http
GET https://api.nue.io/invoices/{invoiceId}
```

### 4. Customer-Individual Invoice

```http
GET https://api.nue.io/customers/{customerId}/invoices/{invoiceId}
```

### Query Parameters

**Pagination:**

- `page` - Page number (1-based, default: 1)
- `limit` - Records per page (1-500, default: 100)

**Filtering:**

- `paymentStatus` - Filter by payment status
- `status` - Filter by invoice status
- `customerId` - Filter by customer ID

**Data Enrichment:**

- `includes=assets,orders,paymentApplications` - Include related data

### Example: Fetch Customer Invoices

```javascript
const response = await fetch('https://api.nue.io/customers/001KS00000DVz1aYAD/invoices?status=Active&includes=assets', {
  headers: {
    'nue-api-key': 'YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  }
});

const result = await response.json();
console.log(`Found ${result.pagination.total} invoices`);
```

### Example: Advanced Filtering

```javascript
// Get invoices by payment status
const response = await fetch('https://api.nue.io/invoices?paymentStatus=Open', {
  headers: { 'nue-api-key': 'YOUR_API_KEY_HERE' }
});
```

### Legacy customerIds Support

The legacy customerIds parameter is still supported for backwards compatibility:

```javascript
const customerIds = '["001KS00000DVz1aYAD","002KS00000DVz1bYAD"]';
const response = await fetch(`https://api.nue.io/invoices?customerIds=${encodeURIComponent(customerIds)}`, {
  headers: { 'nue-api-key': 'YOUR_API_KEY_HERE' }
});
```

### GraphQL Endpoint (Advanced)

For advanced users who need direct GraphQL access, you can still use the GraphQL endpoint:

**Endpoint:**

```json
POST https://api.nue.io/orders/async/graphql
```

**Query:**

```graphql
query {
  Invoice(
    where: {_and: [{customer: {id: {_eq: "001KS00000DVz1aYAD"}}}, {status: {_eq: "Active"}}]}
  ) {
    amount
    amountWithoutTax
    balance
    createdDate
    customerId
    dueDate
    endDate
    invoiceDate
    name
    invoicePdf
    paymentStatus
    startDate
    status
    taxAmount
  }
}
```

## Activate Invoices

Activating an invoice moves it from a "Draft" status to "Active", making it payable and visible for collection workflows. ([Activate Invoices](https://api-docs.nue.io/activate-invoices))

For example, you can activate a list of invoices by providing the invoice IDs in the API request:

```curl
curl -X POST "https://api.nue.io/billing/invoices:activate" \
  -H "nue-api-key: {yourApiKey}" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -d '{
    "invoiceIds": ["5622f52c-c234-4981-8ea3-aa58dc578604"]
  }'
```

You can use a GraphQL filter in the API request to activate invoices that match the filter conditions, such as activating all draft invoices:

```curl
curl -X POST "https://api.nue.io/billing/invoices:activate" \
  -H "nue-api-key: {yourApiKey}" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -d '{
    "graphqlFilter": "{status: {_eq: \"Draft\"}}"
  }'
```

Additionally, you are allowed to change the Invoice Date or add a comment when activating an invoice:

```curl
curl -X POST "https://api.nue.io/billing/invoices:activate" \
  -H "nue-api-key: {yourApiKey}" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -d '{
    "invoiceIds": ["5622f52c-c234-4981-8ea3-aa58dc578604"],
    "invoiceDate":"2025-07-01",
    "invoiceComment": {
        "comment": "Approve and activate the invoice"
    }
  }'
```

:::hint{type="info"}
Please note that if you change the Invoice Date when activating an invoice, the invoice Due Date will be recalculated automatically.
:::

## Cancel Invoices

For invoices with incorrect data or if you want to regenerate new invoices for a specific billing period, you can cancel the invoices through the Nue API ([Cancel Invoices](https://api-docs.nue.io/cancel-invoices)):

```curl
curl -X POST "https://api.nue.io/billing/invoices:cancel" \
  -H "nue-api-key: {yourApiKey}" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -d '{
    "invoiceIds": ["5622f52c-c234-4981-8ea3-aa58dc578604"],
    "invoiceComment": {
        "comment": "Cancel the invoice due to incorrect billing info"
    }
  }'
```

## Reverse Invoices

In certain regions (such as parts of Europe), canceling an active invoice is not permitted by law. In these cases, use the Reverse Invoices API to permanently negate an active invoice while keeping it historically visible in the system as `Reversed` status. Unlike cancellation, reversal is only available for invoices in `Active` status.

Reverse a list of invoices synchronously:

```curl
curl -X POST "https://api.nue.io/billing/invoices:reverse" \
  -H "nue-api-key: {yourApiKey}" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -d '{
    "invoiceIds": ["c055be5b-8185-4289-9856-098b88dd7049"],
    "invoiceComment": {
        "comment": "Reverse the invoice"
    }
  }'
```

For large batches, use the asynchronous endpoint to avoid timeouts:

```curl
curl -X POST "https://api.nue.io/billing/invoices:async-reverse" \
  -H "nue-api-key: {yourApiKey}" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -d '{
    "invoiceIds": ["c055be5b-8185-4289-9856-098b88dd7049"],
    "invoiceComment": {
        "comment": "Reverse the invoice"
    }
  }'
```

Key behaviors when reversing an invoice:

- If the invoice has been fully or partially paid, the payment is refunded and a credit-back credit memo is generated.
- If credit memos have been applied to the invoice, they are unapplied before reversal.
- If a debit memo is associated with the invoice, it is reversed together with the invoice.
- If newer billings exist on the same order products, reversal is blocked with an error.
- Once reversed, the billing state rolls back so the related order products can be billed again in a later billing run.

:::hint{type="info"}
By default, reversed invoices cannot be deleted. Enable the **Allow deleting reversed invoices** setting in Nue System Settings → Invoices to allow deletion of reversed invoices via UI or API.
:::

## Delete Invoices

Once an invoice is in 'Canceled' status and there are no payment actions applied to this invoice, you are allowed to delete it ([Delete Invoices](https://api-docs.nue.io/delete-invoices)):

```curl
curl -X DELETE "https://api.nue.io/billing/invoices" \
  -H "nue-api-key: {yourApiKey}" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -d '{
    "invoiceIds": ["5622f52c-c234-4981-8ea3-aa58dc578604"],
    "graphqlFilter": "{status: {_eq: \"Canceled\"}}"
  }'
```

## Update an Invoice

For invoices with 'Draft', 'Pending Activation', and 'Active' statuses, you can make changes to certain fields and custom fields. Please note that this API ([Update Invoice](https://api-docs.nue.io/update-invoice-fields)) only supports updating one invoice at a time.

For example, you can change an invoice's bill to contact and the due date using the below API:

```curl
curl -X PATCH "https://api.nue.io/billing/invoices/{invoiceId}" \
  -H "nue-api-key: {yourApiKey}" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -d '{
    "dueDate": "2025-08-30",
    "billToContactId": "003KS000005IMUiYAO"
  }'
```

The updated invoice will be returned:

```json
{
    "activatedById": "424cb15f-da63-4d6a-b397-c15142058084",
    "salesAccountId": "001KS00000DVz1aYAD",
    "endDate": "2025-06-30",
    "dueDate": "2025-08-30",
    "source": "Billing",
    "taxStatus": "Not Calculated",
    "shippingAndHandling": 0,
    "balance": 226.330000000,
    "vatMessages": null,
    "id": "c52f7158-b164-44fa-93c5-e4b16420c371",
    "billToContactId":"003KS000005IMUiYAO",
    "einvoicingMandateId": null,
    "createdById": "424cb15f-da63-4d6a-b397-c15142058084",
    "taxCompanyCode": null,
    "einvoicingDocStatus": null,
    "appliedByObject": null,
    "targetDate": "2025-06-30",
    "name": "INV-00000311",
    "externalTaxId": null,
    "currencyIsoCode": null,
    "taxAmount": 0,
    "isCatchUp": false,
    "startDate": "2025-01-01",
    "status": "Active",
    "syncTime": "2025-06-30T09:58:13.844+00:00",
    "poNumbers": null,
    "customFields": null,
    "taxErrorMessage": null,
    "poDates": null,
    "appliedById": null,
    "lastModifiedById": "424cb15f-da63-4d6a-b397-c15142058084",
    "customerId": "001KS00000DVz1aYAD",
    "paymentDetails": null,
    "paymentStatus": "NotTransferred",
    "einvoicingMessage": null,
    "cancellationDate": null,
    "amountWithoutTax": 226.330000000,
    "amount": 226.330000000,
    "comments": "[{\"comment\": \"Approve and activate the invoice\", \"createTime\": \"2025-06-30T09:39:21Z\", \"createUserName\": \"JQ Test Administrator\"}]",
    "lastModifiedDate": "2025-06-30T09:58:12.870+00:00",
    "recordType": "Invoice",
    "einvoicingMandateCode": null,
    "entityId": null,
    "invoiceDate": "2025-07-01",
    "accountingStatus": "Not Started",
    "invoicePdf": "https://app.perftest.nue.io/view-invoice/BPq4JWQgmAWID1sizNNO8jZxZ0xIPknvWJ7iVn0rmC8L1wXqmxQbWOsrpdADN3U9WGwuGoDHlK8nm0khyaksSbhd5qElbHA8HkG0DxoaWOK-0GMpxpLR1fXfdxglYISsa0nBFWWzV7JIvE2KexCOaTM2t8os2QR",
    "paymentHostedUrl": null,
    "createdDate": "2025-06-30T09:33:52.471+00:00",
    "activatedTime": "2025-06-30T09:39:21.165+00:00",
    "tenantId": "b5919513-9625-48d1-9954-8e2998ec0592",
    "externalInvoiceId": null,
    "einvoicingDocId": null
}
```