GET
/
invoices
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request GET "$LAGO_URL/api/v1/invoices?page=2&per_page=20&external_customer_id=hooli_1234" \
  --header "Authorization: Bearer $API_KEY"

{
  "invoices": [
    {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "billing_entity_code": "acme_corp",
      "sequential_id": 2,
      "number": "LAG-1234-001-002",
      "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": "EUR",
      "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,
      "prepaid_credit_amount_cents": 0,
      "progressive_billing_credit_amount_cents": 0,
      "total_amount_cents": 100,
      "version_number": 3,
      "self_billed": false,
      "file_url": "https://getlago.com/invoice/file",
      "created_at": "2022-04-29T08:59:51Z",
      "updated_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",
        "address_line2": null,
        "applicable_timezone": "America/Los_Angeles",
        "city": "Woodland Hills",
        "country": "US",
        "currency": "USD",
        "email": "dinesh@piedpiper.test",
        "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,
        "created_at": "2022-04-29T08:59:51Z",
        "updated_at": "2022-04-29T08:59:51Z",
        "finalize_zero_amount_invoice": "inherit",
        "skip_invoice_custom_sections": false,
        "billing_configuration": {
          "invoice_grace_period": 3,
          "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",
          "address_line2": null,
          "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",
            "external_customer_id": "cus_12345",
            "sync_with_provider": true,
            "subsidiary_id": "2"
          }
        ]
      },
      "billing_period": [
        {
          "lago_subscription_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "external_subscription_id": "external_id",
          "lago_plan_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "subscription_from_datetime": "2022-04-29T08:59:51Z",
          "subscription_to_datetime": "2022-05-29T08:59:51Z",
          "charges_from_datetime": "2022-04-29T08:59:51Z",
          "charges_to_datetime": "2022-05-29T08:59:51Z",
          "invoicing_reason": "subscription_starting"
        }
      ],
      "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",
          "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "fees_amount_cents": 20000
        }
      ],
      "applied_usage_thresholds": [
        {
          "lifetime_usage_amount_cents": 2000,
          "created_at": "2023-11-07T05:31:56Z",
          "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
  }
}
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request GET "$LAGO_URL/api/v1/invoices?page=2&per_page=20&external_customer_id=hooli_1234" \
  --header "Authorization: Bearer $API_KEY"

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
page
integer

Page number.

Example:

1

​
per_page
integer

Number of records per page.

Example:

20

​
external_customer_id
string

Unique identifier assigned to the customer in your application.

Example:

"5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"

​
amount_from
integer

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

Example:

9000

​
amount_to
integer

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

Example:

100000

​
issuing_date_from
string

Filter invoices starting from a specific date.

Example:

"2022-07-08"

​
issuing_date_to
string

Filter invoices up to a specific date.

Example:

"2022-08-09"

​
status
enum<string>

Filter invoices by status. Possible values are draft or finalized.

Available options:
draft,
finalized
​
payment_status
enum<string>

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

Available options:
pending,
failed,
succeeded
​
payment_overdue
boolean

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

Example:

true

​
search_term
string

Search invoices by id, number, customer name, customer external_id or customer email.

Example:

"Jane"

​
currency
string

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

Example:

"EUR"

​
payment_dispute_lost
boolean

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

Example:

true

​
invoice_type
enum<string>

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

Available options:
subscription,
add_on,
credit,
one_off,
advance_charges,
progressive_billing
​
self_billed
boolean

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

Example:

true

​
billing_entity_codes
string[]

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

Example:
["acme_corp", "foo_bar"]
​
metadata[key]
string

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.

Example:

"someValue"

Response

200
application/json

Invoices

The response is of type object.