# List invoices

> Lists your invoices, newest first. To get the next page, pass the `public_id` of the last invoice you received as `starting_after`. You have reached the end when a page has fewer invoices than `limit`.

Source: https://help.boltapp.com/api-reference/invoicing/invoices/listinvoices

`GET /v1/invoices`

## OpenAPI definition

This endpoint as it appears in the OpenAPI document, with every schema it references included.

```json
{
  "openapi": "3.2.0",
  "info": {
    "title": "Invoicing API",
    "version": "v1",
    "description": "API for creating and managing invoices, and for listing a customer's invoices in the customer portal."
  },
  "servers": [
    {
      "url": "https://api.boltapp.com",
      "description": "The Production URL (Live Data)."
    },
    {
      "url": "https://api-sandbox.boltapp.com",
      "description": "The Sandbox URL (Test Data)."
    },
    {
      "url": "https://api-staging.boltapp.com",
      "description": "The Staging URL (Staged Data)."
    }
  ],
  "security": [
    {
      "X-API-Key": [],
      "X-Publishable-Key": []
    }
  ],
  "paths": {
    "/v1/invoices": {
      "get": {
        "operationId": "listInvoices",
        "summary": "List invoices",
        "description": "Lists your invoices, newest first.\n\nTo get the next page, pass the `public_id` of the last invoice you received as `starting_after`. You have reached the end when a page has fewer invoices than `limit`.\n",
        "tags": [
          "Invoices"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "status",
            "schema": {
              "$ref": "#/components/schemas/InvoiceStatus"
            },
            "required": false,
            "description": "Only return invoices with this status."
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "required": false,
            "description": "How many invoices to return. Values above 100 are treated as 100."
          },
          {
            "in": "query",
            "name": "starting_after",
            "schema": {
              "type": "string"
            },
            "required": false,
            "description": "Public ID of an invoice. Returns the invoices created before it.",
            "examples": {
              "default": {
                "value": "inv_9Pq3Xw7Rt2"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of invoices.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "invoices": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Invoice"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid parameters or an unknown `starting_after` invoice."
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "InvoiceStatus": {
        "type": "string",
        "enum": [
          "draft",
          "finalized",
          "sent",
          "paid",
          "past_due",
          "uncollectible",
          "voided"
        ],
        "description": "- `draft`: being prepared. Can be edited or deleted.\n- `finalized`: locked and ready to send.\n- `sent`: sent to the customer and awaiting payment.\n- `paid`: paid in full.\n- `past_due`: unpaid after its due date.\n- `uncollectible`: written off as unpaid.\n- `voided`: cancelled.\n",
        "examples": [
          "draft"
        ]
      },
      "Invoice": {
        "type": "object",
        "properties": {
          "public_id": {
            "type": "string",
            "description": "Public ID of the invoice. Starts with `inv_`, or `quo_` for a quote.",
            "examples": [
              "inv_9Pq3Xw7Rt2"
            ]
          },
          "invoice_number": {
            "type": "string",
            "description": "The invoice number. Empty on a draft until it is finalized, if you didn't set one.",
            "examples": [
              "INV-2026-0042"
            ]
          },
          "to_invoice_consumer_id": {
            "type": "string",
            "description": "Public ID of the customer being billed.",
            "examples": [
              "ic_8hTq2Lm4Vx"
            ]
          },
          "from_invoice_consumer_id": {
            "type": "string",
            "description": "Public ID of the party issuing the invoice, if set."
          },
          "status": {
            "$ref": "#/components/schemas/InvoiceStatus"
          },
          "document_type": {
            "type": "string",
            "enum": [
              "invoice",
              "quote"
            ],
            "description": "Whether this is an invoice or a quote.",
            "examples": [
              "invoice"
            ]
          },
          "total_amount": {
            "type": "integer",
            "format": "int64",
            "description": "The full amount billed, including line items, adjustments and any late fee. Payments do not reduce it.",
            "examples": [
              15000
            ]
          },
          "amount_due": {
            "type": "integer",
            "format": "int64",
            "description": "What is still owed. Goes down as payments arrive, and is `0` on a paid invoice.",
            "examples": [
              15000
            ]
          },
          "deposit_amount": {
            "type": "integer",
            "format": "int64",
            "description": "Deposit due up front."
          },
          "late_fee_amount": {
            "type": "integer",
            "format": "int64",
            "description": "Late fee added because the invoice was paid late."
          },
          "early_pay_discount_amount": {
            "type": "integer",
            "format": "int64",
            "description": "Discount for paying early."
          },
          "currency": {
            "type": "string",
            "description": "Three-letter ISO 4217 currency code.",
            "examples": [
              "USD"
            ]
          },
          "payment_link": {
            "type": "string",
            "format": "uri",
            "description": "Link where the customer can pay. Only present while the invoice can be paid."
          },
          "billing_period_start": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the billing cycle, for an invoice raised by a subscription."
          },
          "billing_period_end": {
            "type": "string",
            "format": "date-time",
            "description": "End of the billing cycle, for an invoice raised by a subscription."
          },
          "entity_type": {
            "type": "string",
            "description": "What raised the invoice, for example `subscription`. Absent for an invoice you created directly.",
            "examples": [
              "subscription"
            ]
          },
          "entity_id": {
            "type": "string",
            "description": "Public ID of what raised the invoice, for example the subscription's ID.",
            "examples": [
              "s_3fKq8Lw2Zp"
            ]
          },
          "order_token": {
            "type": "string",
            "description": "Token of the order created for payment, once there is one."
          },
          "quote_accepted_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the customer accepted the quote."
          },
          "issued_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was issued."
          },
          "sent_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was sent to the customer."
          },
          "due_at": {
            "type": "string",
            "format": "date-time",
            "description": "When payment is due."
          },
          "finalized_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was finalized."
          },
          "paid_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was paid in full."
          },
          "voided_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was voided."
          },
          "metadata": {
            "type": "string",
            "description": "Your own notes for this invoice."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was last changed."
          }
        }
      }
    },
    "securitySchemes": {
      "X-API-Key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "X-Publishable-Key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Publishable-Key"
      },
      "PortalToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "A customer portal token."
      },
      "PortalTokenQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "token",
        "description": "A customer portal token, passed as a query parameter."
      }
    }
  }
}
```
