---
updatedAt: 2026-08-24T09:14:57.000Z
agentTools:
projectIndex: https://developers.vibe.co/llms.txt
---
# List invoices
Lists invoices for the authenticated account, optionally filtered by status.
**Scopes:**
`billing:read`
*Rate limits*:
Burst: `10/s`
Steady: `300/m`
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"paths": {
"/billing/invoices": {
"get": {
"description": "Lists invoices for the authenticated account, optionally filtered by status.\n**Scopes:**\n`billing:read`\n
*Rate limits*:
Burst: `10/s`
Steady: `300/m`\n",
"operationId": "listAccountInvoices",
"parameters": [
{
"name": "status",
"required": false,
"in": "query",
"description": "Filter by invoice status",
"schema": {
"type": "string",
"enum": [
"open",
"failed",
"paid",
"void"
]
}
},
{
"name": "limit",
"required": false,
"in": "query",
"description": "Maximum number of invoices to return",
"schema": {
"minimum": 1,
"maximum": 100,
"default": 20,
"type": "number"
}
},
{
"name": "offset",
"required": false,
"in": "query",
"description": "Number of invoices to skip",
"schema": {
"minimum": 0,
"type": "number"
}
},
{
"name": "account_id",
"required": false,
"in": "query",
"description": "Required only for embedded apps.",
"schema": {
"type": "number"
}
}
],
"responses": {
"200": {
"description": "Invoice list",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvoiceList"
}
}
}
},
"400": {
"description": "Bad request error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"missingApiKey": {
"summary": "Missing API key",
"value": {
"error": {
"type": "validation",
"message": "Missing API Key",
"status": 400,
"detail": null,
"request_id": "req_8f3a4b2c",
"doc_url": null
}
}
},
"validationError": {
"summary": "Validation error",
"value": {
"error": {
"type": "validation",
"message": "Validation error",
"status": 400,
"detail": {
"validation": [
"id must be a string"
]
},
"request_id": "req_8f3a4b2c",
"doc_url": null
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"invalidApiKey": {
"summary": "Invalid API key",
"value": {
"error": {
"type": "invalid_token",
"message": "Unauthorized",
"status": 401,
"detail": null,
"request_id": "req_8f3a4b2c",
"doc_url": "https://developers.vibe.co/errors/invalid-token"
}
}
}
}
}
}
},
"403": {
"description": "Insufficient scope error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"insufficientScope": {
"summary": "Missing required scope",
"value": {
"error": {
"type": "insufficient_scope",
"message": "Missing required scope",
"status": 403,
"detail": {
"required": "billing:read",
"granted": [
"test"
]
},
"request_id": "req_8f3a4b2c",
"doc_url": "https://developers.vibe.co/reference/oauth2token"
}
}
}
}
}
}
}
},
"summary": "List invoices",
"tags": [
"Billing"
],
"x-rate-limit": {
"rps": 10,
"rpm": 300
},
"x-scopes": [
"billing:read"
]
}
}
},
"info": {
"title": "Vibe Public API",
"description": "Vibe Public API revision 2026-06-01",
"version": "2026-06-01",
"contact": {}
},
"tags": [
{
"name": "Billing",
"description": "Read-only views of what an Account owes and has spent. All amounts are in cents.\n\nThe balance is the authoritative figure for what is owed. It is read from a running total rather than summed from the cash-operations list, so the two are not expected to match exactly.\n\nCash operations are grouped into one entry per calendar day per type, in the account timezone, matching what the Vibe app shows. `amount_cents` is rounded per entry, so use `total_amount_cents` for an exact total over a window.\n\n> ⚠️ **Gotcha — operation windows are bounded by volume, not duration**\n>\n> A window covering more than 50,000 operations is rejected with `400`. Ad spend is recorded hourly, so a one-year window is well inside that; only windows spanning several years of continuous spend approach it. Narrow `from`/`to` if you hit it: the window is aggregated before `limit`/`offset` are applied, so paging cannot bring an oversized one under the limit."
}
],
"servers": [
{
"url": "https://api.vibe.co",
"description": "Production API"
}
],
"components": {
"securitySchemes": {
"bearer": {
"scheme": "bearer",
"bearerFormat": "JWT",
"type": "http"
}
},
"schemas": {
"ErrorDetail": {
"type": "object",
"properties": {
"required": {
"type": "string",
"example": "audiences:write"
},
"granted": {
"example": [
"audiences:read",
"reporting:read"
],
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"required",
"granted"
]
},
"ApiError": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"insufficient_scope",
"invalid_token",
"validation",
"internal_error"
]
},
"message": {
"type": "string"
},
"status": {
"type": "number",
"example": 403
},
"detail": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/ErrorDetail"
}
]
},
"request_id": {
"type": "string",
"example": "req_8f3a4b2c"
},
"doc_url": {
"type": "string",
"example": "https://developers.vibe.co/reference/oauth2token",
"nullable": true
}
},
"required": [
"type",
"message",
"status",
"request_id"
]
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/ApiError"
}
},
"required": [
"error"
]
},
"Invoice": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Invoice identifier",
"format": "uuid"
},
"status": {
"type": "string",
"description": "Invoice status",
"enum": [
"open",
"failed",
"paid",
"void"
]
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "usd"
},
"amount_cents": {
"type": "number",
"description": "Invoice amount in cents (integer, no decimals)"
},
"amount_paid_cents": {
"type": "number",
"description": "Amount paid in cents (integer, no decimals)"
},
"payment_retries": {
"type": "number",
"description": "Number of payment retries attempted"
},
"created_at": {
"type": "string",
"description": "When the invoice was created",
"format": "date-time"
},
"paid_at": {
"type": "object",
"nullable": true,
"description": "When the invoice was paid",
"format": "date-time"
}
},
"required": [
"id",
"status",
"currency",
"amount_cents",
"amount_paid_cents",
"payment_retries",
"created_at",
"paid_at"
]
},
"InvoiceList": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Invoice"
}
},
"total": {
"type": "number",
"description": "Total number of invoices matching filters"
},
"limit": {
"type": "number",
"description": "Maximum number of items returned"
},
"offset": {
"type": "number",
"description": "Number of items skipped"
}
},
"required": [
"data",
"total",
"limit",
"offset"
]
}
}
},
"security": [
{
"bearer": []
}
]
}
```