GEgetlago
customers
invoices

List all customer's invoices

Changed on

This endpoint is used for retrieving all invoices of a customer.

get/customers/{external_customer_id}/invoices

Request

Path parameters

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

The customer external unique identifier (provided by your own application)

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.

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 the customer's invoices by id or number. Customer attributes are not searched here, because the list is already scoped to one customer.

payment_dispute_lostboolean
Example:true

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

invoice_type'subscription' | 'add_on' | 'credit' | 'one_off' | 'advance_charges' | 'progressive_billing'

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.

currencystring
Example:EUR

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

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"
]
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