Manage Invoices

20 min

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

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

2. Customer-Scoped Invoices

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

3. Individual Invoice

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

4. Customer-Individual Invoice

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

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

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

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:

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

Query:

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)

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

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 -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 -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"
    }
  }'

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

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

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

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

{
    "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
}