List Invoices

Use when listing or searching invoices (e.g. admin view or customer history). Returns a paginated list; supports filtering by customer, status, date range.

GET /v1/invoices

cURL

curl -X GET "https://api.flexprice.io/v1/invoices?customer_id=cust_1234&invoice_status=FINALIZED&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

200

{
  "data": [
    {
      "id": "inv_1234567890",
      "customer_id": "cust_1234",
      "subscription_id": "sub_5678",
      "invoice_number": "INV-2024-0001",
      "invoice_type": "SUBSCRIPTION",
      "invoice_status": "FINALIZED",
      "payment_status": "PAID",
      "currency": "usd",
      "amount_due": "100.00",
      "amount_paid": "100.00",
      "amount_remaining": "0.00",
      "subtotal": "100.00",
      "total_tax": "0.00",
      "total_discount": "0.00",
      "total": "100.00",
      "total_prepaid_credits_applied": "0.00",
      "due_date": "2024-02-01T00:00:00Z",
      "period_start": "2024-01-01T00:00:00Z",
      "period_end": "2024-01-31T23:59:59Z",
      "billing_period": "MONTHLY",
      "billing_reason": "subscription_cycle",
      "line_items": [],
      "metadata": {},
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T00:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Query Parameters

customer_id · string

Filter invoices by customer ID

subscription_id · string

Filter invoices by subscription ID

invoice_status · string

Filter by invoice status

Values: DRAFT, FINALIZED, VOIDED, UNCOLLECTIBLE

payment_status · string

Filter by payment status

Values: PENDING, PAID, UNPAID, PARTIALLY_PAID, OVERPAID, FAILED

invoice_type · string

Filter by invoice type

Values: SUBSCRIPTION, ONE_TIME, CREDIT, PRORATION

due_date_from · string

Filter invoices with due date on or after this date (ISO 8601 format)

due_date_to · string

Filter invoices with due date on or before this date (ISO 8601 format)

period_start_from · string

Filter invoices with billing period starting on or after this date (ISO 8601 format)

period_start_to · string

Filter invoices with billing period starting on or before this date (ISO 8601 format)

limit · integer · default: "10"

Number of invoices to return per page (max 100)

offset · integer · default: "0"

Number of invoices to skip for pagination

sort_by · string · default: "created_at"

Field to sort by

Values: created_at, updated_at, due_date, period_start, total

sort_order · string · default: "desc"

Sort order

Values: asc, desc

Response

data · array

Array of invoice objects

Show Invoice object

id · string

Unique identifier for the invoice

customer_id · string

ID of the customer this invoice belongs to

subscription_id · string

ID of the subscription (if applicable)

invoice_number · string

Human-readable invoice number

invoice_type · string

Type of invoice (SUBSCRIPTION, ONE_TIME, CREDIT, PRORATION)

invoice_status · string

Current status (DRAFT, FINALIZED, VOIDED, UNCOLLECTIBLE)

payment_status · string

Payment status (PENDING, PAID, UNPAID, PARTIALLY_PAID, OVERPAID, FAILED)

currency · string

Three-letter ISO currency code (e.g., USD, EUR)

amount_due · string

Total amount due

amount_paid · string

Amount already paid

amount_remaining · string

Remaining amount to be paid

subtotal · string

Subtotal before taxes and discounts

total_tax · string

Total tax amount

total_discount · string

Total discount amount

total · string

Final total amount

total_prepaid_credits_applied · string

Total prepaid credits applied to this invoice

due_date · string

Date when payment is due (ISO 8601 format)

period_start · string

Start of billing period (ISO 8601 format)

period_end · string

End of billing period (ISO 8601 format)

billing_period · string

Billing period (MONTHLY, YEARLY, etc.)

billing_reason · string

Reason for invoice creation

line_items · array

Array of line items included in the invoice

metadata · object

Custom metadata key-value pairs

created_at · string

Timestamp when invoice was created

updated_at · string

Timestamp when invoice was last updated

total · integer

Total number of invoices matching the filter criteria

limit · integer

Number of invoices returned per page

offset · integer

Number of invoices skipped

cURL

curl -X GET "https://api.flexprice.io/v1/invoices?customer_id=cust_1234&invoice_status=FINALIZED&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

200

{
  "data": [
    {
      "id": "inv_1234567890",
      "customer_id": "cust_1234",
      "subscription_id": "sub_5678",
      "invoice_number": "INV-2024-0001",
      "invoice_type": "SUBSCRIPTION",
      "invoice_status": "FINALIZED",
      "payment_status": "PAID",
      "currency": "usd",
      "amount_due": "100.00",
      "amount_paid": "100.00",
      "amount_remaining": "0.00",
      "subtotal": "100.00",
      "total_tax": "0.00",
      "total_discount": "0.00",
      "total": "100.00",
      "total_prepaid_credits_applied": "0.00",
      "due_date": "2024-02-01T00:00:00Z",
      "period_start": "2024-01-01T00:00:00Z",
      "period_end": "2024-01-31T23:59:59Z",
      "billing_period": "MONTHLY",
      "billing_reason": "subscription_cycle",
      "line_items": [],
      "metadata": {},
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T00:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}