customers

List all customers

Changed on Nov 3, 2026

This endpoint retrieves all existing customers.

get/customers

Request

Base URL
https://api.getlago.com/api/v1
Auth
HTTP bearer
TypeScript
https://skmtc.dev/getlago/apis/lago-api-documentation/docs/customers/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_idstring

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

Filter customers by external ID.

account_type[]string[]

Filter customers by account type.

[
  "customer",
  "partner"
]

billing_entity_codes[]string[]

Filter customers by billing entity codes.

[
  "billing_entity_code_1",
  "billing_entity_code_2"
]

search_termstring

Example:John Doe

Filter customers by search term. This will filter all customers whose name, firstname, lastname, legal name, external id or email contain the search term.

countries[]Country[]

Filter customers by countries. Possible values are the ISO 3166-1 alpha-2 codes.

[
  "US",
  "FR"
]

states[]string[]

Filter customers by states.

[
  "CA",
  "Paris"
]

zipcodes[]string[]

Filter customers by zipcodes.

[
  "10115",
  "75001"
]

currencies[]Currency[]

Filter customers by currencies.

[
  "USD",
  "EUR"
]

has_tax_identification_numberboolean

Example:true

Filter customers by whether they have a tax identification number or not.

metadata[key]string

Example:value

Filter customers by metadata. Replace key with the actual metadata key you want to match, and provide the corresponding value. Providing empty value will search for customers without given metadata key. For example, metadata[is_synced]=true&metadata[last_synced_at]=.

customer_type'company' | 'individual'

Example:company

Filter customers by customer type.

has_customer_typeboolean

Example:true

Filter customers by whether they have a customer type or not.

Response

List of customers

Example response

{
  "customers": [
    {
      "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"
        }
      ],
      "taxes": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "name": "TVA",
          "code": "french_standard_vat",
          "description": "French standard VAT",
          "rate": 20,
          "applied_to_organization": true,
          "applied_to_billing_entities_codes": [
            "acme_corp",
            "foo_bar"
          ],
          "created_at": "2023-07-06T14:35:58Z"
        }
      ],
      "applicable_invoice_custom_sections": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "name": "EU Bank Details",
          "code": "eu_bank_details",
          "description": "This section contains the bank details for EU customers.",
          "details": "Bank Name: Lago Bank, IBAN: FR7630004000031234567890143",
          "display_name": "Bank Details:",
          "applied_to_organization": true,
          "organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "created_at": "2023-07-06T14:35:58Z"
        }
      ],
      "error_details": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "error_code": "tax_error",
          "details": {
            "tax_error": "taxDateTooFarInFuture"
          }
        }
      ]
    }
  ],
  "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
- 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 TND 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 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 external_id
- info
  added the enum value SYP to the property items/ of the query request parameter currencies[]
- info
  added the enum value TND to the property items/ of the query request parameter currencies[]
- info
  added the non-success 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
  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
  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