Skip to main content
Retrieve a list of invoices for your customers. You can filter by customer and entity, and control pagination.
Invoices are automatically created when customers subscribe to plans, make payments, or when billing events occur. This is a read-only endpoint.

​
Query Parameters

​
customer_id
string
required
Filter invoices by customer ID (your unique customer identifier)
​
entity_id
string
Filter invoices by entity ID. If provided, returns invoices for this specific entity plus any customer-level invoices (where entity_id is null)
​
limit
integer
default:"100"
Maximum number of invoices to return (max: 100)

​
Response

Returns an array of invoice objects with the following properties:
​
plan_ids
string[]
Array of plan IDs included in this invoice
​
stripe_id
string
The Stripe invoice ID
​
status
string
The invoice status. Possible values: draft, open, paid, void, uncollectible
​
total
number
The total amount of the invoice in the smallest currency unit (e.g., cents for USD)
​
currency
string
Three-letter ISO currency code (e.g., usd, eur)
​
created_at
number
Timestamp when the invoice was created (milliseconds since epoch)
​
hosted_invoice_url
string | null
URL to the invoice page where customers can view and pay the invoice
[
  {
    "plan_ids": ["pro_plan", "addon_storage"],
    "stripe_id": "in_1A2B3C4D5E6F7G8H",
    "status": "paid",
    "total": 2999,
    "currency": "usd",
    "created_at": 1759247877000,
    "hosted_invoice_url": "https://invoice.stripe.com/i/acct_123/test_456"
  },
  {
    "plan_ids": ["starter_plan"],
    "stripe_id": "in_9H8G7F6E5D4C3B2A",
    "status": "open",
    "total": 999,
    "currency": "usd",
    "created_at": 1756569477000,
    "hosted_invoice_url": "https://invoice.stripe.com/i/acct_123/test_789"
  }
]

​
Common Use Cases

const response = await fetch(
  'https://api.autumn.com/v1/invoices?customer_id=cus_123&limit=50',
  {
    headers: {
      'Authorization': `Bearer ${process.env.AUTUMN_SECRET_KEY}`
    }
  }
);

const invoices = await response.json();
console.log(`Found ${invoices.length} invoices`);

​
Invoice Statuses

  • draft - Invoice is still being prepared
  • open - Invoice has been finalized and is awaiting payment
  • paid - Invoice has been successfully paid
  • void - Invoice has been voided and cannot be paid
  • uncollectible - Payment attempts have failed and the invoice is marked as uncollectible

​
Line Items

Invoices contain line items that detail the charges. Each line item includes:
  • Plan or feature being charged
  • Billing period (start and end dates)
  • Amount and currency
  • Quantity (for metered or seat-based billing)
  • Proration adjustments (for mid-cycle changes)
To access detailed line item information, use the Get Invoice endpoint with a specific stripe_id.

Build docs developers (and LLMs) love

Get started for freeTalk to us