Command reference

Commands follow one shape:

lago <resource> <action> [identifier] [flags]

Every command answers --help with its full flag list. Four rules apply everywhere:

Flags are API fields. A snake_case field becomes a --kebab-case flag. Nested fields carry their parent as a prefix: billing_configuration.payment_provider is --billing-configuration-payment-provider.
Objects and arrays take JSON. --metadata '[{"key":"tier","value":"gold","display_in_invoice":false}]'.
--input takes the whole body. Inline JSON or @file.json. Use it for deeply nested payloads such as plan charges. The body is wrapped exactly as the API expects.
Identifiers are positional, and their kind depends on the resource. Passing the wrong kind returns a not-found error that names the resource type, exit code 4.

Resource	Positional identifier
customers, customer wallets, payment methods	`external_customer_id` (yours)
subscriptions	`external_id` (yours)
billable metrics, plans, coupons, add-ons, taxes, features, billing entities	`code`
invoices, credit notes, fees, payments, payment requests, wallets, webhook endpoints, quotes, orders	`lago_id` (Lago’s UUID)
events	`transaction_id`

Output on these pages

The right column shows what each command prints. Creates and updates print the identifier block by default. Reads print the full resource, shown here as --output json because that is the form to script against. Response bodies follow the Lago API schema, so the API reference documents every field. The global flags (--output, --query, --dry-run, --confirm, --profile, --mode), exit codes, pagination, and safety gates are covered in the Lago CLI overview.

Command groups

Setup and diagnostics

init, whoami, doctor, version, upgrade, completion

Helpers

api, docs, alias, seed, fixtures, logs tail

Billable metrics

Define what you meter.

Plans

Plans, charges, fixed charges, filters, metadata.

Features and entitlements

Features, privileges, plan entitlements, subscription overrides.

Customers

Customers, current and past usage, portal and checkout URLs.

Subscriptions

Assign, override, alert, terminate.

Events

Send one, stream NDJSON, batch, estimate.

Invoices

List, preview, finalize, void, download, payment URL.

Credit notes

Estimate, issue, void.

Coupons and add-ons

Discounts and one-off items.

Wallets

Prepaid credits, top-ups, alerts.

Taxes and fees

Tax rates and fee inspection.

Payments

Payments, requests, receipts, payment methods.

Webhooks

Endpoints and signature keys.

Analytics and logs

MRR, revenue, usage, audit and API logs.

Organization

Organization settings and billing entities.

Quotes and orders

Quotes, order forms, orders.

lago customers create --external-id acme_001 --name "Acme Inc." --currency USD
lago customers get acme_001
lago customers get acme_001 --output json --query 'customer.email'
lago customers list --limit 5
lago customers delete acme_001 --confirm acme_001

# A plan code passed where a subscription external ID belongs
lago events send --external-subscription-id ai_plan_gpt4_tokens --code api_calls
echo $?

LAGO_ID      1a901a90-1a90-1a90-1a90-1a901a901a90
EXTERNAL_ID  acme_001
NAME         Acme Inc.

{
  "customer": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "sequential_id": 1,
    "slug": "LAG-1234-001",
    "external_id": "acme_001",
    "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": "billing@acme.example",
    "legal_name": "Coleman-Blair",
    "legal_number": "49-008-2965",
    "logo_url": "http://hooli.com/logo.png",
    "name": "Acme Inc.",
    "firstname": "Gavin",
    "lastname": "Belson",
    "account_type": "customer",
    "customer_type": "company",
    "phone": "1-171-883-3711 x245",
    "state": "CA",
    "tax_identification_number": "EU123456789",
    "timezone": "America/New_York",
    "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",
    "skip_invoice_custom_sections": false,
    "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",
      "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",
        "targeted_object": "contacts",
        "email": "dinesh@piedpiper.test"
      }
    ],
    "taxes": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "name": "TVA",
        "code": "french_standard_vat",
        "description": "French standard VAT",
        "rate": 20,
        "applied_to_organization": true,
        "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"
        }
      }
    ]
  }
}

"dinesh@piedpiper.test"

Error: no subscription "ai_plan_gpt4_tokens" exists in this organization
Suggestion: Check that each identifier is the right kind for the flag it was passed to: a plan code is not a subscription external ID, and a Lago ID is not an external ID.
$ echo $?
4

Introduction

Get started

Events & Usage Components

Pricing & Subscriptions

Quotes & Order Forms

Invoicing

Payments & Cash Collection

AI Agents and MCP

Data & Analytics

Revenue recognition

Resources

Command reference

Output on these pages

Command groups

Setup and diagnostics

Helpers

Billable metrics

Plans

Features and entitlements

Customers

Subscriptions

Events

Invoices

Credit notes

Coupons and add-ons

Wallets

Taxes and fees

Payments

Webhooks

Analytics and logs

Organization

Quotes and orders

​Output on these pages

​Command groups

Setup and diagnostics

Helpers

Billable metrics

Plans

Features and entitlements

Customers

Subscriptions

Events

Invoices

Credit notes

Coupons and add-ons

Wallets

Taxes and fees

Payments

Webhooks

Analytics and logs

Organization

Quotes and orders

Output on these pages

Command groups