> ## Documentation Index > Fetch the complete documentation index at: https://docs.getlago.com/llms.txt > Use this file to discover all available pages before exploring further. # Customers > Create and inspect customers, read current and past usage, generate portal and checkout URLs. | Command | Description | | --------------------------------------------------------------- | -------------------------------------------------------------- | | `customers create` | Create or update a customer. The API upserts on `external_id`. | | `customers get ` | Retrieve a customer. | | `customers list` | List customers with filters. | | `customers delete ` | Delete a customer. Confirmation-gated. | | `customers export` | Trigger a customers export. | | `customers current-usage ` | Usage for the open billing period. | | `customers past-usage ` | Usage for closed periods. | | `customers projected-usage ` | Projected usage to period end. | | `customers subscriptions ` | The customer's subscriptions. | | `customers invoices ` | The customer's invoices. | | `customers credit-notes ` | The customer's credit notes. | | `customers applied-coupons ` | Coupons applied to the customer. | | `customers payments`, `payment-requests ` | Payments and payment requests. | | `customers portal-url ` | Generate a customer portal URL. | | `customers checkout-url ` | Generate a payment-provider checkout URL. | ## create `external_id` is your identifier and the one every other command uses to address the customer. Running `create` again with the same `external_id` updates the customer. | Flag | Description | | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `--external-id`, `--name`, `--email`, `--currency` | The essentials. Currency is locked once the customer has an invoice. | | `--country`, `--timezone`, `--net-payment-term` | Billing address, local time for billing, days to pay. | | `--billing-configuration-payment-provider`, `-payment-provider-code`, `-provider-customer-id`, `-sync-with-provider` | Link to a payment provider connection, or let Lago create the provider customer. | | `--billing-configuration-provider-payment-methods` | JSON array, Stripe only: `["card","sepa_debit"]`. | | `--billing-entity-code` | Attach to a billing entity other than the default. | | `--metadata` | JSON array of `{"key","value","display_in_invoice"}`. | | `--tax-codes`, `--invoice-custom-section-codes` | JSON arrays of codes. | ## Usage Usage hangs off the customer and takes the subscription's external ID as a flag. Three identifiers, three kinds: passing a plan code as `--external-subscription-id` is a not-found error, exit 4, not an empty usage report. | Flag | Description | | -------------------------------------------------------- | --------------------------------------------------------------------------------- | | `--external-subscription-id` | Required. | | `--charge-code`, `--charge-id`, `--billable-metric-code` | Narrow to one charge or metric. | | `--full-usage true` | Since subscription start instead of the current period. Requires a charge filter. | | `--group` | Filter by pricing group, `group[cloud]=aws`. | | `--apply-taxes false` | Exclude taxes from the amounts. | | `--periods-count N` | `past-usage` only: how many closed periods. | In the response, `units` is a decimal string and every `*_amount_cents` is an integer. Compare `total_amount_cents` with the dashboard and they match. ## delete Deletion is confirmation-gated. Non-interactive scripts pass `--confirm` with the same `external_customer_id`. A mismatch is refused, exit 2. ```bash create theme={"dark"} lago customers create \ --external-id acme_001 \ --name "Acme Inc." \ --email billing@acme.example \ --currency USD \ --country US --timezone America/New_York \ --net-payment-term 30 # Attach to a payment provider connection lago customers create --external-id acme_001 --name "Acme Inc." \ --billing-configuration-payment-provider stripe \ --billing-configuration-payment-provider-code stripe_prod \ --billing-configuration-sync-with-provider true \ --billing-configuration-provider-payment-methods '["card","sepa_debit"]' # Tag test data: visible in the dashboard, kept off invoices lago customers create --external-id qa_cust_001 --name "QA Test Company" --currency USD \ --metadata '[{"key":"mode","value":"test","display_in_invoice":false}]' ``` ```bash get theme={"dark"} lago customers get acme_001 lago customers get acme_001 --output json --query 'customer.email' lago customers get acme_001 --output json --query 'customer.metadata' ``` ```bash list theme={"dark"} lago customers list --limit 5 lago customers list --search-term acme lago customers list --countries US,CA --currencies USD lago api GET '/customers?metadata[mode]=test' # metadata filters take the raw query form lago customers list --output json --query "customers[?starts_with(external_id, 'qa_')].external_id" lago customers list --all --output json \ | jq -r '.customers[] | select(.external_id | startswith("qa_")) | .external_id' ``` ```bash current-usage theme={"dark"} lago customers current-usage acme_001 --external-subscription-id acme_001_pro lago customers current-usage acme_001 --external-subscription-id acme_001_pro \ --output json --query 'customer_usage.total_amount_cents' lago customers current-usage acme_001 --external-subscription-id acme_001_pro \ --output json --query 'customer_usage.charges_usage[].{metric: billable_metric.code, units: units, amount: amount_cents}' # One charge, since subscription start lago customers current-usage acme_001 --external-subscription-id acme_001_pro \ --charge-code api_requests --full-usage true ``` ```bash past-usage theme={"dark"} lago customers past-usage acme_001 --external-subscription-id acme_001_pro --periods-count 3 lago customers projected-usage acme_001 --external-subscription-id acme_001_pro ``` ```bash related theme={"dark"} lago customers subscriptions acme_001 lago customers invoices acme_001 lago customers credit-notes acme_001 lago customers applied-coupons acme_001 lago customers payments acme_001 lago customers portal-url acme_001 --output json --query 'customer.portal_url' lago customers checkout-url acme_001 # Find the owner when you only have the subscription lago subscriptions get acme_001_pro --output json --query 'subscription.external_customer_id' ``` ```bash delete theme={"dark"} lago customers delete qa_cust_001 --confirm qa_cust_001 ``` ```text create theme={"dark"} LAGO_ID 1a901a90-1a90-1a90-1a90-1a901a901a90 EXTERNAL_ID acme_001 NAME Acme Inc. ``` ```json get theme={"dark"} { "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" } } ] } } ``` ```json list theme={"dark"} { "customers": [ { "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" } } ] } ], "meta": { "current_page": 2, "next_page": 3, "prev_page": 1, "total_pages": 4, "total_count": 70 } } ``` ```json current-usage theme={"dark"} { "customer_usage": { "from_datetime": "2022-07-01T00:00:00Z", "to_datetime": "2022-07-31T23:59:59Z", "issuing_date": "2022-08-01", "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "currency": "USD", "amount_cents": 123, "taxes_amount_cents": 200, "total_amount_cents": 123, "charges_usage": [ { "units": "1.0", "total_aggregated_units": "1.0", "events_count": 10, "amount_cents": 123, "amount_currency": "USD", "pricing_unit_details": { "amount_cents": 200, "short_name": "CR", "conversion_rate": "0.5" }, "charge": { "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "charge_model": "graduated", "invoice_display_name": "Setup" }, "billable_metric": { "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "name": "Storage", "code": "storage", "aggregation_type": "sum_agg" }, "filters": [ {} ], "grouped_usage": [ {} ], "presentation_breakdowns": [ {} ] } ] } } ``` ```json portal-url theme={"dark"} { "customer": { "portal_url": "https://app.lago.com/customer-portal/1234567890" } } ``` ```text delete (no --confirm) theme={"dark"} Error: confirmation required for qa_cust_001 Suggestion: Pass --confirm "qa_cust_001" or rerun in an interactive terminal. $ echo $? 2 ```