invoices

List all invoices

Changed on Nov 3, 2026

This endpoint is used for retrieving all invoices.

get/invoices

Request

Base URL
https://api.getlago.com/api/v1
Auth
HTTP bearer
TypeScript
https://skmtc.dev/getlago/apis/lago-api-documentation/docs/invoices/get.ts
A function with typed inputs. Its response is checked against the schema.

Query parameters

pageinteger

Example:1

Page number. Defaults to 1. A value that is not a positive integer, such as 0, returns the first page.

per_pageinteger

Example:20

Number of records per page. Defaults to 100. The maximum is 200, unless another maximum is configured for your organization. A value above the maximum returns a 422 error with value_is_out_of_range on per_page. A value that is not a positive integer, such as 0, returns the default number of records.

external_customer_idstring

Example:5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba

Unique identifier assigned to the customer in your application.

amount_frominteger

Example:9000

Filter invoices of at least a specific amount. This parameter must be defined in cents to ensure consistent handling for all currency types.

amount_tointeger

Example:100000

Filter invoices up to a specific amount. This parameter must be defined in cents to ensure consistent handling for all currency types.

issuing_date_fromstring date

Example:2022-07-08

Filter invoices starting from a specific date.

issuing_date_tostring date

Example:2022-08-09

Filter invoices up to a specific date.

status'draft' | 'finalized' | 'failed' | 'pending' | 'voided'

Filter invoices by status. Possible values are draft, failed, finalized, pending and voided.

statuses[]string[]

Filter invoices by statuses. Possible values are draft, failed, finalized, pending and voided.

payment_status'pending' | 'failed' | 'succeeded'

Filter invoices by payment status. Possible values are pending, failed or succeeded.

payment_statuses[]string[]

Filter invoices by payment statuses. Possible values are pending, failed or succeeded.

payment_overdueboolean

Example:true

Filter invoices by payment_overdue. Possible values are true or false.

search_termstring

Example:Jane

Search invoices by id, number, purchase order number, or by the name, legal name, first name, last name, external_id or email of the customer.

currencystring

Example:EUR

Filter invoices by currency. Possible values ISO 4217 currency codes.

payment_dispute_lostboolean

Example:true

Filter invoices with a payment dispute lost. Possible values are true or false.

partially_paidboolean

Example:true

Filter invoices that are partially paid. When true, only invoices with a non-zero amount paid that is below the total due are returned. When false, those invoices are excluded.

settlements[]string[]

Filter invoices settled by at least one of the given settlement types. payment matches invoices settled by a payment, credit_note matches invoices settled by a credit note.

[
  "payment",
  "credit_note"
]

Filter invoices by invoice type. Possible values are subscription, add_on, credit, one_off, advance_charges or progressive_billing.

self_billedboolean

Example:true

Filter invoices by self billed. Possible values are true or false.

billing_entity_codes[]string[]

Filter invoices by billing entity codes. Possible values are the billing entity codes you have created.

[
  "acme_corp",
  "foo_bar"
]

metadata[key]string

Example:someValue

Filter invoices by metadata. Replace key with the actual metadata key you want to match, and provide the corresponding value. Providing empty value will search for invoice without given metadata key. For example, metadata[color]=blue.

purchase_order_numberstring

Example:PO-123

Filter by the invoice purchase order number. The match is exact but case-insensitive.

Response

Invoices

Example response

{
  "invoices": [
    {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "billing_entity_code": "acme_corp",
      "sequential_id": 2,
      "number": "LAG-1234-001-002",
      "purchase_order_number": "PO-123",
      "issuing_date": "2022-04-30",
      "payment_dispute_lost_at": "2022-09-14T16:35:31Z",
      "payment_due_date": "2022-04-30",
      "payment_overdue": true,
      "net_payment_term": 30,
      "invoice_type": "subscription",
      "status": "finalized",
      "payment_status": "succeeded",
      "currency": "USD",
      "fees_amount_cents": 100,
      "coupons_amount_cents": 10,
      "credit_notes_amount_cents": 10,
      "sub_total_excluding_taxes_amount_cents": 100,
      "taxes_amount_cents": 20,
      "sub_total_including_taxes_amount_cents": 120,
      "total_amount_cents": 100,
      "total_paid_amount_cents": 40,
      "total_offsetted_credit_note_amount_cents": 10,
      "total_due_amount_cents": 50,
      "version_number": 3,
      "file_url": "https://getlago.com/invoice/file",
      "xml_url": "https://getlago.com/invoice/xml",
      "web_url": "https://app.getlago.com/acme/customer/1a901a90-1a90-1a90-1a90-1a901a901a90/invoice/2b012b01-2b01-2b01-2b01-2b012b012b01/overview",
      "created_at": "2022-04-29T08:59:51Z",
      "updated_at": "2022-04-29T08:59:51Z",
      "voided_at": "2022-04-29T08:59:51Z",
      "customer": {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "sequential_id": 1,
        "slug": "LAG-1234-001",
        "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        "billing_entity_code": "acme_corp",
        "address_line1": "5230 Penfield Ave",
        "applicable_timezone": "America/Los_Angeles",
        "city": "Woodland Hills",
        "country": "US",
        "currency": "USD",
        "email": "dinesh@piedpiper.example",
        "legal_name": "Coleman-Blair",
        "legal_number": "49-008-2965",
        "logo_url": "http://hooli.com/logo.png",
        "name": "Gavin Belson",
        "firstname": "Gavin",
        "lastname": "Belson",
        "account_type": "customer",
        "customer_type": "company",
        "phone": "1-171-883-3711 x245",
        "state": "CA",
        "tax_identification_number": "EU123456789",
        "timezone": "America/Los_Angeles",
        "url": "http://hooli.com",
        "zipcode": "91364",
        "net_payment_term": 30,
        "external_salesforce_id": "0015p00001JQx1QAAT",
        "created_at": "2022-04-29T08:59:51Z",
        "updated_at": "2022-04-29T08:59:51Z",
        "finalize_zero_amount_invoice": "inherit",
        "billing_configuration": {
          "invoice_grace_period": 3,
          "subscription_invoice_issuing_date_anchor": "next_period_start",
          "subscription_invoice_issuing_date_adjustment": "keep_anchor",
          "payment_provider": "stripe",
          "payment_provider_code": "stripe-eu-1",
          "provider_customer_id": "cus_12345",
          "sync": true,
          "sync_with_provider": true,
          "document_locale": "fr",
          "provider_payment_methods": [
            "card",
            "sepa_debit",
            "us_bank_account",
            "bacs_debit",
            "link",
            "boleto",
            "crypto",
            "customer_balance"
          ]
        },
        "shipping_address": {
          "address_line1": "5230 Penfield Ave",
          "city": "Woodland Hills",
          "country": "US",
          "state": "CA",
          "zipcode": "91364"
        },
        "metadata": [
          {
            "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "key": "Purchase Order",
            "value": "123456789",
            "display_in_invoice": true,
            "created_at": "2022-04-29T08:59:51Z"
          }
        ],
        "integration_customers": [
          {
            "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "type": "netsuite",
            "integration_code": "netsuite-eu-1",
            "code": "netsuite-eu-1",
            "is_default": true,
            "category": "accounting",
            "external_customer_id": "cus_12345",
            "sync_with_provider": true,
            "subsidiary_id": "2",
            "targeted_object": "contacts",
            "email": "dinesh@piedpiper.example"
          }
        ]
      },
      "metadata": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "key": "digital_ref_id",
          "value": "INV-0123456-98765",
          "created_at": "2022-04-29T08:59:51Z"
        }
      ],
      "applied_taxes": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "lago_tax_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "tax_name": "TVA",
          "tax_code": "french_standard_vat",
          "tax_rate": 20,
          "tax_description": "French standard VAT",
          "amount_cents": 2000,
          "amount_currency": "USD",
          "created_at": "2022-09-14T16:35:31Z"
        }
      ],
      "applied_invoice_custom_sections": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "code": "eu_bank_details",
          "details": "Bank Name: Lago Bank, IBAN: FR7630004000031234567890143",
          "display_name": "Bank Details:",
          "created_at": "2023-07-06T14:35:58Z"
        }
      ],
      "applied_usage_thresholds": [
        {
          "lifetime_usage_amount_cents": 2000,
          "created_at": "2025-03-31T12:31:44Z",
          "usage_threshold": {
            "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "threshold_display_name": "Threshold 1",
            "amount_cents": 10000,
            "recurring": true,
            "created_at": "2023-06-27T19:43:42Z",
            "updated_at": "2023-06-27T19:43:42Z"
          }
        }
      ]
    }
  ],
  "meta": {
    "current_page": 2,
    "next_page": 3,
    "prev_page": 1,
    "total_pages": 4,
    "total_count": 70
  }
}

Changes

Nov 3, 20265d26657495a3 Revision changes
- breaking
  the response property /////// became nullable for the status
- info
  added the new optional query request parameter payment_status
- info
  added the new optional query request parameter status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property //////// became required for the status
- info
  the response property /////// became required for the status
- info
  the response property /////// became required for the status
- info
  the response property /////// became required for the status
Oct 16, 2026fce1879654d8 Revision changes
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ///////// became nullable for the status
- breaking
  the response property ///////// became nullable for the status
- breaking
  the response property ///////// became nullable for the status
- breaking
  the response property ///////// became nullable for the status
- warning
  added the new SYP enum value to the ////// response property for the response status
- warning
  added the new SYP enum value to the ///////// response property for the response status
- warning
  added the new SYP enum value to the //////// response property for the response status
- warning
  added the new TND enum value to the ////// response property for the response status
- warning
  added the new TND enum value to the ///////// response property for the response status
- warning
  added the new TND enum value to the //////// response property for the response status
- warning
  added the new advance_charges enum value to the ////// response property for the response status
- warning
  added the new avalara enum value to the /////// response property for the response status
- warning
  added the new cashfree enum value to the ///////// response property for the response status
- warning
  added the new deleted enum value to the ////// response property for the response status
- warning
  added the new flutterwave enum value to the ///////// response property for the response status
- warning
  added the new moneyhash enum value to the ///////// response property for the response status
- warning
  added the new undefined enum value to the ///////// response property for the response status
- info
  added the new optional query request parameter partially_paid
- info
  added the new optional query request parameter purchase_order_number
- info
  added the new optional query request parameter settlements[]
- info
  added the optional property //////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
- info
  added the required property ////// to the response with the status
- info
  added the required property ////// to the response with the status
- info
  added the required property ////// to the response with the status
- info
  added the required property ////// to the response with the status
- info
  added the required property ////// to the response with the status
- info
  added the required property ////// to the response with the status
- info
  added the required property ////// to the response with the status

Operation history (10 revisions)

List all invoices

Request

Query parameters

Response 200OK

Example response

Changes

Response