List Invoices

The List Invoices endpoint retrieves all invoices associated with your authenticated application. This endpoint provides comprehensive invoice data including customer information, payment status, line items, and financial totals with support for pagination and filtering.

Endpoint Details

Method: GET
URL: /api/v0/invoices
Authentication: Required (API Key & Secret)
Content-Type: application/json
Rate Limiting: 100 requests per minute

Authentication

This endpoint requires API key authentication using:

x-client-key: Your API client key
x-client-secret: Your API client secret

Query Parameters

Pagination Parameters

Parameter	Type	Description	Default	Example
skip	integer	Number of records to skip	0	`?skip=20`
take	integer	Number of records to return	10	`?take=50`

Filtering Parameters

Parameter	Type	Description	Example
status	enum	Filter by invoice status	`?status=OPEN`
customer	string	Filter by customer ID	`?customer=customer-uuid`
from_date	string	Filter invoices from date (YYYY-MM-DD)	`?from_date=2024-01-01`
to_date	string	Filter invoices to date (YYYY-MM-DD)	`?to_date=2024-12-31`

Response

Success Response (200 OK)

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "invoice_number": "INV-001234",
    "name": "Website Development Services",
    "app_id": "app_123456789",
    "email": "client@example.com",
    "address": "123 Business St, City, State",
    "phone_number": "+1-555-123-4567",
    "logo": "https://mycompany.com/assets/logo.png",
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "customer": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "client@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "Example Corp",
      "created_at": "2024-01-10T08:00:00.000Z"
    },
    "walletId": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "wallet": {
      "id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
      "currency": "USDC",
      "chain": "ethereum",
      "address": "0x1234...5678"
    },
    "items": [
      {
        "id": "item_123456789",
        "product_id": "prod_123456789",
        "product": {
          "id": "prod_123456789",
          "name": "Website Development",
          "description": "Custom website development services",
          "price": 5000.00,
          "currency": "USDC"
        },
        "quantity": 1,
        "line_total": 5000.00
      }
    ],
    "due_date": "2024-02-15T00:00:00.000Z",
    "send_date": "2024-01-15T00:00:00.000Z",
    "date_created": "2024-01-15T10:30:00.000Z",
    "status": "OPEN",
    "payment_methods": ["CRYPTO", "BANK_TRANSFER"],
    "delivery": "EMAIL",
    "payment_link": true,
    "partial_payment": false,
    "taxId": "tax_550e8400-e29b-41d4-a716-446655440123",
    "tax": {
      "id": "tax_550e8400-e29b-41d4-a716-446655440123",
      "name": "Sales Tax",
      "percentage": 8.25,
      "active": true
    },
    "currency": "USDC",
    "subtotal": 5000.00,
    "tax_amount": 412.50,
    "total_amount": 5412.50,
    "transactions": [
      {
        "id": "tx_123456789",
        "amount": 2706.25,
        "currency": "USDC",
        "status": "COMPLETED",
        "created_at": "2024-01-20T14:30:00.000Z",
        "payment_method": "CRYPTO"
      }
    ],
    "amount_paid": 2706.25,
    "amount_due": 2706.25,
    "is_overdue": false
  },
  {
    "id": "660f9500-f30c-52e5-b827-557766551111",
    "invoice_number": "INV-001235",
    "name": "Monthly Subscription - January 2024",
    "app_id": "app_123456789",
    "email": "billing@subscriptionco.com",
    "address": null,
    "phone_number": null,
    "logo": null,
    "customer_id": "660f9500-f30c-52e5-b827-557766551111",
    "customer": {
      "id": "660f9500-f30c-52e5-b827-557766551111",
      "email": "billing@subscriptionco.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "company_name": "Subscription Co",
      "created_at": "2024-01-05T12:00:00.000Z"
    },
    "walletId": "bcde2345-6789-01fg-hijk-lmnopqrstuvw",
    "wallet": {
      "id": "bcde2345-6789-01fg-hijk-lmnopqrstuvw",
      "currency": "USDC",
      "chain": "polygon",
      "address": "0x5678...9012"
    },
    "items": [
      {
        "id": "item_987654321",
        "product_id": "prod_987654321",
        "product": {
          "id": "prod_987654321",
          "name": "Premium Subscription",
          "description": "Monthly premium service subscription",
          "price": 99.00,
          "currency": "USDC"
        },
        "quantity": 1,
        "line_total": 99.00
      }
    ],
    "due_date": "2024-02-01T00:00:00.000Z",
    "send_date": "2024-01-25T00:00:00.000Z",
    "date_created": "2024-01-25T09:15:00.000Z",
    "status": "PAID",
    "payment_methods": ["CRYPTO"],
    "delivery": "EMAIL",
    "payment_link": true,
    "partial_payment": false,
    "taxId": null,
    "tax": null,
    "currency": "USDC",
    "subtotal": 99.00,
    "tax_amount": 0.00,
    "total_amount": 99.00,
    "transactions": [
      {
        "id": "tx_987654321",
        "amount": 99.00,
        "currency": "USDC",
        "status": "COMPLETED",
        "created_at": "2024-01-28T16:45:00.000Z",
        "payment_method": "CRYPTO"
      }
    ],
    "amount_paid": 99.00,
    "amount_due": 0.00,
    "is_overdue": false
  }
]

Response Fields

Invoice Object

Field	Type	Description
id	string	Unique identifier for the invoice
invoice_number	string	Auto-generated invoice number (INV-XXXXXX)
name	string	Invoice name/title
app_id	string	Application ID that created the invoice
email	string	Customer email address
address	string	Customer address (optional)
phone_number	string	Customer phone number (optional)
logo	string	Company logo URL (optional)
customer_id	string	Customer identifier
customer	object	Customer details
walletId	string	Wallet used for payment processing
wallet	object	Wallet details
items	array	Invoice line items with product details
due_date	string	Payment due date (ISO 8601)
send_date	string	Date invoice was sent (ISO 8601)
date_created	string	Invoice creation date (ISO 8601)
status	enum	Invoice status
payment_methods	array	Accepted payment methods
delivery	enum	Delivery method
payment_link	boolean	Whether payment link was generated
partial_payment	boolean	Whether partial payments are allowed
taxId	string	Tax configuration ID (optional)
tax	object	Tax details (optional)
currency	enum	Invoice currency
subtotal	number	Subtotal amount before tax
tax_amount	number	Tax amount
total_amount	number	Total amount including tax
transactions	array	Payment transactions
amount_paid	number	Total amount paid
amount_due	number	Remaining amount due
is_overdue	boolean	Whether invoice is past due date

Customer Object

Field	Type	Description
id	string	Customer unique identifier
email	string	Customer email address
first_name	string	Customer first name
last_name	string	Customer last name
company_name	string	Customer company name
created_at	string	Customer creation date (ISO 8601)

Item Object

Field	Type	Description
id	string	Line item unique identifier
product_id	string	Product identifier
product	object	Product details
quantity	number	Quantity of the product
line_total	number	Total for this line item

Example Requests

curl -X GET "https://api.devdraft.ai/api/v0/invoices" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Error Responses

{
  "statusCode": 401,
  "message": "Application not authenticated",
  "error": "Unauthorized"
}

Filtering and Pagination

Pagination Strategy

Offset-Based Pagination

skip: Number of records to skip (offset)
take: Number of records to return (limit)
Default: skip=0, take=10
Maximum: take=1000 per request

Performance Considerations

Large datasets may require multiple requests
Use appropriate take values to balance performance and data needs
Consider caching for frequently accessed data

Status Filtering

Invoice Status Values

DRAFT: Invoice created but not sent
OPEN: Invoice sent and awaiting payment
PAID: Invoice fully paid
PASTDUE: Invoice overdue for payment
PARTIALLYPAID: Partial payment received

Common Filter Combinations

# Active invoices (open + overdue)
?status=OPEN,PASTDUE

# Paid invoices for accounting
?status=PAID&from_date=2024-01-01

# All unpaid invoices
?status=OPEN,PASTDUE,PARTIALLYPAID

Date Range Filtering

Date Field Options

from_date: Filter invoices created on or after this date
to_date: Filter invoices created on or before this date
Format: YYYY-MM-DD (ISO 8601 date format)

Common Date Ranges

# Current month
?from_date=2024-01-01&to_date=2024-01-31

# Last quarter
?from_date=2023-10-01&to_date=2023-12-31

# Year to date
?from_date=2024-01-01

Use Cases

Invoice Dashboard

Display all invoices with status indicators and payment tracking

Collections Management

Track overdue invoices and manage collection processes

Revenue Reporting

Generate financial reports and revenue analytics

Customer Analysis

Analyze customer payment patterns and invoice history

Payment Reconciliation

Match payments with invoices for accounting purposes

Compliance Auditing

Review invoice history for regulatory compliance

Implementation Examples

const InvoiceDashboard = async () => {
  const summary = await InvoiceManager.getInvoicesSummary();
  const overdueInvoices = await InvoiceManager.getOverdueInvoices();
  const recentInvoices = await getInvoices({ take: 10 });
  
  return {
    overview: {
      totalInvoices: summary.draft + summary.open + summary.paid + summary.pastdue + summary.partiallyPaid,
      totalValue: summary.totalValue,
      paidValue: summary.paidValue,
      outstandingValue: summary.outstandingValue,
      collectionRate: summary.collectionRate
    },
    statusBreakdown: {
      draft: summary.draft,
      open: summary.open,
      paid: summary.paid,
      pastdue: summary.pastdue,
      partiallyPaid: summary.partiallyPaid
    },
    alerts: {
      overdueCount: overdueInvoices.length,
      overdueValue: overdueInvoices.reduce((sum, inv) => sum + inv.amount_due, 0)
    },
    recentActivity: recentInvoices.map(inv => ({
      id: inv.id,
      number: inv.invoice_number,
      customer: inv.customer.company_name || `${inv.customer.first_name} ${inv.customer.last_name}`,
      amount: inv.total_amount,
      status: inv.status,
      dueDate: inv.due_date
    }))
  };
};

Performance Considerations

Pagination Best Practices

Use appropriate page sizes (10-100 records) for UI display
Implement cursor-based pagination for large datasets
Cache frequently accessed invoice lists
Consider server-side filtering for complex queries

Data Loading Strategies

Load invoice summaries first, then details on demand
Use lazy loading for invoice line items and related data
Implement progressive loading for dashboard analytics
Cache customer and product data to reduce API calls

Real-time Updates

Use webhooks to receive invoice status updates
Implement optimistic UI updates for better user experience
Cache invoice data with appropriate TTL values
Consider WebSocket connections for real-time dashboards

Security Considerations

Invoice data contains sensitive financial information. Ensure proper access controls and data protection measures.

Data Access Control

Invoice data is automatically scoped to your authenticated application
Only invoices created by your application are returned
Business-level isolation prevents cross-business data access

Sensitive Data Handling

Customer payment information requires secure transmission
Implement audit logging for invoice data access
Consider data encryption for stored invoice information

Compliance Requirements

Maintain records for tax and regulatory compliance
Implement data retention policies as required
Ensure proper access controls for financial data

Rate Limiting

This endpoint is subject to the standard API rate limits:

Production: 100 requests per minute per API key
Development: 50 requests per minute per API key

For large datasets, use appropriate pagination parameters and implement caching to stay within rate limits.

POST /api/v0/invoices - Create a new invoice
GET /api/v0/invoices/{id} - Fetch specific invoice details
PATCH /api/v0/invoices/{id} - Update invoice configuration
GET /api/v0/customers - List customers for invoice creation

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

Endpoint Details

Authentication

Query Parameters

Filtering Parameters

Response

Success Response (200 OK)

Response Fields

Invoice Object

Customer Object

Item Object

Example Requests

Error Responses

Status Filtering

Date Range Filtering

Use Cases

Invoice Dashboard

Collections Management

Revenue Reporting

Customer Analysis

Payment Reconciliation

Compliance Auditing

Implementation Examples

Performance Considerations

Security Considerations

Rate Limiting

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

​Endpoint Details

​Authentication

​Query Parameters

​Pagination Parameters

​Filtering Parameters

​Response

​Success Response (200 OK)

​Response Fields

​Invoice Object

​Customer Object

​Item Object

​Example Requests

​Error Responses

​Filtering and Pagination

​Pagination Strategy

​Status Filtering

​Date Range Filtering

​Use Cases

Invoice Dashboard

Collections Management

Revenue Reporting

Customer Analysis

Payment Reconciliation

Compliance Auditing

​Implementation Examples

​Performance Considerations

​Security Considerations

​Rate Limiting

​Related Endpoints

Endpoint Details

Authentication

Query Parameters

Pagination Parameters

Filtering Parameters

Response

Success Response (200 OK)

Response Fields

Invoice Object

Customer Object

Item Object

Example Requests

Error Responses

Filtering and Pagination

Pagination Strategy

Status Filtering

Date Range Filtering

Use Cases

Implementation Examples

Performance Considerations

Security Considerations

Rate Limiting

Related Endpoints