Invoices API
The Invoices API allows you to manage invoices for your customers. You can retrieve lists of invoices, get details for a specific invoice, and download PDF versions.
Overview
Invoices are generated automatically as part of the billing cycle, but this API allows for manual retrieval and management. Key features include:
- Listing invoices with filtering and pagination.
- Retrieving detailed information for a single invoice, including line items and payment status.
- Securely downloading PDF versions of invoices via presigned URLs.
- Manually triggering a payment retry for unpaid invoices.
Authentication
All API requests require authentication via merchant credentials.
Endpoints
Get All Invoices
Retrieves a paginated list of all invoices for the authenticated merchant, with optional filtering by customer or status.
GET https://api.getlumen.dev/v1/invoices?customerId={customerId}&status={status}&limit={limit}&offset={offset}Query Parameters
| Parameter | Type | Description |
|---|---|---|
customerId | string | Filter invoices by a specific customer ID. |
status | string | Filter invoices by status (e.g., paid, unpaid, draft). |
limit | number | The number of invoices to return (default: 20). |
offset | number | The number of invoices to skip (for pagination). |
Response
{
"invoices": [
{
"id": "inv_123",
"customerId": "cust_456",
"status": "paid",
"totalAmountCents": 5000,
"currency": "USD",
"issueDate": "2024-01-15T10:30:00Z",
"hasPdf": true,
"customer": {
"id": "cust_456",
"name": "John Doe"
}
}
],
"pagination": {
"total": 1,
"limit": 20,
"offset": 0
}
}Get Invoice by ID
Retrieves a single invoice by its ID, including detailed information about line items, payments, and related customer and subscription data.
GET https://api.getlumen.dev/v1/invoices/{id}Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The ID of the invoice. |
Response
{
"invoice": {
"id": "inv_123",
"status": "paid",
"totalAmountCents": 5000,
"currency": "USD",
"issueDate": "2024-01-15T10:30:00Z",
"hasPdf": true,
"lineItems": [
{
"id": "li_123",
"description": "Pro Plan",
"subtotalCents": 5000
}
],
"payment": {
"id": "pay_123",
"status": "succeeded"
}
}
}Get Invoices by Customer
Retrieves all invoices for a specific customer.
GET https://api.getlumen.dev/v1/invoices/customer/{customerId}Parameters
| Parameter | Type | Description |
|---|---|---|
customerId | string | The ID of the customer. |
Response
A list of invoice objects, similar to the Get All Invoices endpoint.
Download Invoice PDF
Generates and returns a temporary, secure URL to download the PDF version of an invoice. The URL is valid for 15 minutes.
GET https://api.getlumen.dev/v1/invoices/{id}/pdfParameters
| Parameter | Type | Description |
|---|---|---|
id | string | The ID of the invoice. |
Response
{
"invoice": {
"id": "inv_123",
"customerInvoiceNumber": "INV-0001"
},
"pdfUrl": "https://s3.amazonaws.com/your-bucket/invoice.pdf?AWSAccessKeyId=...",
"expiresIn": 900
}Retry Invoice Payment
Manually triggers a payment retry for an unpaid invoice.
POST https://api.getlumen.dev/v1/invoices/{id}/retry-paymentParameters
| Parameter | Type | Description |
|---|---|---|
id | string | The ID of the invoice to retry. |
Response
{
"success": true,
"message": "Retry queued",
"attemptNumber": 2,
"paymentId": "pay_123"
}