Invoices API Reference

Manage invoices, billing, payment tracking, and invoice-related operations in the billing system.

Base Path: /api/invoices

Overview

The Invoices API provides comprehensive endpoints for managing invoices including creation, retrieval, status tracking, bulk operations, and export functionality. All invoice endpoints support OData filtering and pagination.

Key Operations

API Endpoints

POST /api/invoices

Create Invoice

Creates a new invoice with billing details.

Authentication

Bearer Token or Service Token

Request Body

{
  "customerId": "cust_123",
  "orderId": "ord_456",
  "invoiceNumber": "INV-2026-001",
  "invoiceDate": "2026-06-02T10:30:00Z",
  "dueDate": "2026-06-15T23:59:59Z",
  "items": [
    {
      "description": "Cloud Server Premium",
      "quantity": 1,
      "unitPrice": 299.99,
      "amount": 299.99
    }
  ],
  "subtotal": 299.99,
  "tax": 29.99,
  "total": 329.98,
  "currency": "USD",
  "status": "draft"
}

Response

{
  "id": "inv_789",
  "invoiceNumber": "INV-2026-001",
  "customerId": "cust_123",
  "status": "draft",
  "total": 329.98,
  "createdAt": "2026-06-02T10:30:00Z"
}
GET /api/invoices/{id}

Get Invoice by ID

Gets invoice details by ID with all line items.

Authentication

Bearer Token or Service Token

Path Parameters

Parameter Type
id string

Response

{
  "id": "inv_789",
  "invoiceNumber": "INV-2026-001",
  "customerId": "cust_123",
  "orderId": "ord_456",
  "invoiceDate": "2026-06-02T10:30:00Z",
  "dueDate": "2026-06-15T23:59:59Z",
  "items": [
    {
      "description": "Cloud Server Premium",
      "quantity": 1,
      "unitPrice": 299.99,
      "amount": 299.99
    }
  ],
  "subtotal": 299.99,
  "tax": 29.99,
  "total": 329.98,
  "currency": "USD",
  "status": "issued",
  "createdAt": "2026-06-02T10:30:00Z"
}
GET /api/invoices/odata

List Invoices (OData)

Gets invoices with OData filtering and pagination.

Authentication

Bearer Token or Service Token

Query Parameters

Parameter Type Description
$filter string OData filter expression
$orderby string Sort by columns
$skip integer Skip n records
$top integer Take n records

Response

{
  "value": [
    {
      "id": "inv_789",
      "invoiceNumber": "INV-2026-001",
      "customerId": "cust_123",
      "status": "issued",
      "total": 329.98,
      "dueDate": "2026-06-15T23:59:59Z"
    }
  ],
  "count": 250
}
PUT /api/invoices/{id}

Update Invoice

Updates invoice details (only draft invoices).

Authentication

Bearer Token or Service Token

Request Body

{
  "invoiceNumber": "INV-2026-002",
  "dueDate": "2026-06-20T23:59:59Z",
  "items": [
    {
      "description": "Cloud Server Premium",
      "quantity": 1,
      "unitPrice": 349.99,
      "amount": 349.99
    }
  ],
  "subtotal": 349.99,
  "tax": 34.99,
  "total": 384.98
}

Response

{
  "id": "inv_789",
  "invoiceNumber": "INV-2026-002",
  "status": "draft",
  "total": 384.98,
  "updatedAt": "2026-06-02T11:00:00Z"
}
PATCH /api/invoices/{id}/status

Update Invoice Status

Updates invoice status (draft → issued → paid).

Authentication

Bearer Token or Service Token

Request Body

{
  "status": "issued",
  "reason": "Ready for delivery"
}

Response

{
  "id": "inv_789",
  "invoiceNumber": "INV-2026-001",
  "status": "issued",
  "updatedAt": "2026-06-02T11:05:00Z"
}
POST /api/invoices/bulk-cancel

Bulk Cancel Invoices

Bulk cancels multiple invoices.

Authentication

Bearer Token or Service Token

Request Body

{
  "invoiceIds": ["inv_789", "inv_790", "inv_791"],
  "reason": "Customer request"
}

Response

{
  "cancelled": 3,
  "failed": 0,
  "results": [
    {
      "invoiceId": "inv_789",
      "status": "cancelled"
    }
  ]
}
POST /api/invoices/{id}/export-pdf

Export Invoice as PDF

Exports invoice to PDF format.

Authentication

Bearer Token or Service Token

Response

PDF file download

DELETE /api/invoices/{id}

Delete Invoice

Soft deletes invoice (only draft invoices).

Authentication

Bearer Token or Service Token

Response

{
  "success": true,
  "message": "Invoice deleted"
}

Error Responses

Code HTTP Status Description
INVOICE_NOT_FOUND 404 Invoice does not exist
INVALID_STATUS_TRANSITION 400 Cannot transition to this status
INVOICE_LOCKED 400 Cannot modify issued or paid invoices
INVALID_AMOUNT 400 Invalid invoice amount

Quick Links

← Back to Overview ← Orders API Receipts API → Try the Playground