List Invoices

Retrieve a paginated list of invoices with optional filtering and sorting.

GEThttps://api.zenpayz.com/merchant/api/v1/invoices

Bearer · API key

Request

Headers

Header	Description
Authorization REQUIRED	Bearer {api_key}
X-Signature REQUIRED	HMAC-SHA256 signature
X-Timestamp REQUIRED	ISO 8601 timestamp
X-Secret-Salt REQUIRED	Secret salt for HMAC validation
Content-Type REQUIRED	application/json

Query Parameters

Parameter	Type	Description
status OPTIONAL	string	Filter by status: DRAFT, SENT, VIEWED, PARTIALLY_PAID, PAID, OVERDUE, CANCELLED, VOID
currency OPTIONAL	string	Filter by currency code
customerId OPTIONAL	string	Filter by customer ID
startDate OPTIONAL	string	Filter invoices issued on or after this date (ISO 8601)
endDate OPTIONAL	string	Filter invoices issued on or before this date (ISO 8601)
page OPTIONAL	number	Page number (default: 1)
limit OPTIONAL	number	Items per page (default: 20, max: 100)
sortBy OPTIONAL	string	Sort field (default: createdAt)
sortOrder OPTIONAL	string	Sort direction: ASC or DESC (default: DESC)
searchTerm OPTIONAL	string	Search by invoice number or customer name

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "items": [
      {
        "invoiceId": "inv_a1b2c3d4e5f6g7h8",
        "invoiceNumber": "INV-2024-0001",
        "customerId": "cust_a1b2c3d4e5f6g7h8",
        "customerEmail": "john@example.com",
        "customerName": "John Doe",
        "currency": "USD",
        "status": "SENT",
        "issueDate": "2024-01-15T00:00:00.000Z",
        "dueDate": "2024-02-15T00:00:00.000Z",
        "totalAmount": 275.00,
        "amountPaid": 0,
        "amountDue": 275.00,
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  },
  "message": "Invoices retrieved successfully",
  "error": null,
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "processing_time_ms": 40,
    "api_version": "v1",
    "endpoint": "GET /invoices",
    "user_type": "merchant"
  }
}

Error Responses

Code	HTTP	Message
VALIDATION_ERROR	400	Invalid query parameters
UNAUTHORIZED	401	Invalid API key

Examples

cURL

curl -X GET "https://api.zenpayz.com/merchant/api/v1/invoices?status=SENT&page=1&limit=20" \
  -H "Authorization: Bearer zp_test_xxxxx" \
  -H "X-Timestamp: 2024-01-15T10:30:00.000Z" \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Secret-Salt: your_secret_salt" \
  -H "Content-Type: application/json"

JavaScript

const params = new URLSearchParams({
  status: 'SENT',
  page: '1',
  limit: '20',
});

const response = await fetch(`https://api.zenpayz.com/merchant/api/v1/invoices?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
    'X-Secret-Salt': secretSalt,
    'Content-Type': 'application/json',
  },
});

const result = await response.json();
console.log(result.data.items); // Array of invoices
console.log(result.data.total); // Total count

SDK

const invoices = await zenpays.invoices.list({
  status: 'SENT',
  page: 1,
  limit: 20,
});

console.log(invoices.items); // Array of invoices
console.log(invoices.total); // Total count

Related Endpoints

• Create Invoice
• Get Invoice
• Invoice Analytics