Lago Python Client

https://github.com/getlago/lago-python-client
Admin
A Python wrapper for the Lago API that enables developers to interact with Lago's billing and...
Tokens:174,487
Snippets:1,039
Trust Score:9.5
License:MIT
Update:6 days ago
Show doc for...
Tokens:
Raw
### Usage examples for customer operations

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/customers.md

Shows how to create a customer, retrieve usage data, list customer-scoped resources, and get portal/checkout URLs. Requires a valid API key.

```python
from lago_python_client import Client
from lago_python_client.models.customer import Customer

client = Client(api_key="sk_live_123")

customer = Customer(external_id="cus_1", name="Acme", currency="USD", email="billing@acme.io")
created = client.customers.create(customer)

# usage
usage = client.customers.current_usage("cus_1", external_subscription_id="sub_1", full_usage=True)
print(usage.amount_cents)

projected = client.customers.projected_usage("cus_1", "sub_1")
periods = client.customers.past_usage("cus_1", "sub_1", {"per_page": 5})

# customer-scoped lists
invoices = client.customer_invoices.find_all("cus_1", {"status": "finalized"})
subs = client.customer_subscriptions.find_all("cus_1")

# customer portal / checkout
print(client.customers.portal_url("cus_1"))
print(client.customers.checkout_url("cus_1"))
```

--------------------------------

### Find usage example

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/base-client.md

Example of finding a plan by its code.

```python
plan = client.plans.find("plan_code_1")
```

--------------------------------

### FindAll usage example

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/base-client.md

Example of listing invoices with pagination and extracting the results.

```python
result = client.invoices.find_all({"per_page": 10, "page": 1})
invoices, meta = result["invoices"], result["meta"]
```

--------------------------------

### Install development dependencies

Source: https://github.com/getlago/lago-python-client/blob/main/README.md

Upgrade pip, setuptools, and wheel, then install the package with test and lint extras.

```bash
python -m pip install --upgrade pip setuptools wheel
python -m pip install '.[test,lint]'
```

--------------------------------

### Full configuration example

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/configuration.md

Shows how to instantiate the Client with all configuration options, including API key, custom URLs, retry settings, and a rate limit observer. The example also demonstrates accessing the resulting rate limit retry config and base URLs.

```python
import logging

from lago_python_client import Client
from lago_python_client.observability import LoggingRateLimitObserver

client = Client(
    api_key="sk_live_123",
    api_url="https://billing.internal.example.com",   # self-hosted
    use_ingest_service=True,                          # separate ingest endpoint
    ingest_api_url="https://ingest.internal.example.com",
    max_retries=5,
    retry_on_rate_limit=True,
    on_rate_limit_info=LoggingRateLimitObserver(
        thresholds=(0.50, 0.80, 0.95),
        logger=logging.getLogger("app.billing"),
        level=logging.INFO,
    ),
)

# `client.rate_limit_retry_config` now holds max_retries=5 etc.
assert client.rate_limit_retry_config.max_retries == 5
print(client.base_api_url)         # https://billing.internal.example.com/api/v1/
print(client.base_ingest_api_url)  # https://ingest.internal.example.com/api/v1/
```

--------------------------------

### Update usage example

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/base-client.md

Example of updating a plan with a specific identifier.

```python
updated = client.plans.update(Plan(code="plan_1", amount_cents=2000), identifier="plan_1")
```

--------------------------------

### Install lago-python-client via poetry

Source: https://github.com/getlago/lago-python-client/blob/main/README.md

Alternative installation using Poetry from PyPI.

```shell
$ poetry add "lago-python-client"
```

--------------------------------

### Destroy usage example

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/base-client.md

Example of deleting a tax by its code.

```python
deleted = client.taxes.destroy("tax_code_1")
```

--------------------------------

### Usage example for analytics clients

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/analytics.md

Shows how to instantiate the client and call find_all on each analytics resource. The example uses an API key and demonstrates passing query parameters like currency and billable_metric_code.

```python
from lago_python_client import Client

client = Client(api_key="sk_live_123")

result = client.gross_revenues.find_all({"currency": "USD"})
print(result["gross_revenues"], result["meta"])

client.mrrs.find_all()
client.usages.find_all({"billable_metric_code": "page_views"})
client.invoice_collections.find_all()
client.invoiced_usages.find_all()
client.overdue_balances.find_all()

```

--------------------------------

### Install lago-python-client via pip

Source: https://github.com/getlago/lago-python-client/blob/main/README.md

Install the package from PyPI using pip.

```shell
$ python -m pip install "lago-python-client"
```

--------------------------------

### Create usage examples

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/base-client.md

Basic usage and custom timeout with error handling for the create method.

```python
# basic
client = Client(api_key="...")
created = client.add_ons.create(AddOn(code="support", amount_cents=1000, amount_currency="USD"))
```

```python
# custom timeout, error handling
try:
    result = client.customers.create(customer, timeout=httpx.Timeout(30.0))
except LagoRateLimitError as e:
    print(e.limit, e.remaining, e.reset)
```

--------------------------------

### GET /plans

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Lists all plans.

```APIDOC
## GET /plans

### Description
Lists all plans.

### Method
GET

### Endpoint
/plans

```

--------------------------------

### find_all

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/add-ons.md

Lists all add-ons with optional pagination. Sends a GET request to /api/v1/add_ons.

```APIDOC
## GET /api/v1/add_ons

### Description
Lists all add-ons with optional pagination.

### Method
GET

### Endpoint
/api/v1/add_ons

### Parameters
#### Query Parameters
- **options** (QueryPairs) - Optional - Query parameters such as pagination (e.g., per_page, page).
- **timeout** (Optional[httpx.Timeout]) - Optional - Per-request timeout. Default: httpx.Timeout(10.0).

### Response
#### Success Response (200)
- **add_ons** (array of AddOnResponse) - List of add-ons.
- **meta** (object) - Pagination metadata.

#### Response Example
{
  "add_ons": [
    {
      "lago_id": "...",
      "code": "priority-support",
      "name": "Priority Support",
      "amount_cents": 5000,
      "amount_currency": "USD"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

### Errors
- **LagoApiError** / **LagoRateLimitError** - Thrown on non-2xx responses.
```

--------------------------------

### Error handling example

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/analytics.md

Demonstrates catching LagoApiError when calling find_all. The example shows accessing status_code and detail attributes on the exception.

```python
from lago_python_client.exceptions import LagoApiError

try:
    client.mrrs.find_all({"from_date": "2024-01"})
except LagoApiError as e:
    print(e.status_code, e.detail)

```

--------------------------------

### Error handling example

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/add-ons.md

Demonstrates catching LagoApiError when an add-on is not found. Prints status_code, detail, and url from the exception.

```python
from lago_python_client import Client
from lago_python_client.exceptions import LagoApiError

client = Client(api_key="sk_live_123")
try:
    client.add_ons.find("does-not-exist")
except LagoApiError as e:
    print(e.status_code, e.detail, e.url)
```

--------------------------------

### GET /fees

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Lists all fees.

```APIDOC
## GET /fees

### Description
Lists all fees.

### Method
GET

### Endpoint
/fees

```

--------------------------------

### Error handling example

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/quotes.md

Shows how to catch LagoApiError when approving a quote version, printing the status code and detail.

```python
from lago_python_client.exceptions import LagoApiError

try:
    client.quote_versions.approve("qv_missing")
except LagoApiError as e:
    print(e.status_code, e.detail)
```

--------------------------------

### FindAllCommandMixin.find_all signature

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/base-client.md

Signature for the find_all method. GETs a list of resources with optional query parameters.

```python
def find_all(
    self: _ClientMixin[_M],
    options: QueryPairs = None,
    timeout: Optional[httpx.Timeout] = DEFAULT_TIMEOUT,
) -> Mapping[str, Any]:
```

--------------------------------

### find

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/base-client.md

Fetches a single resource by its ID using a GET request. Returns the resource model instance.

```APIDOC
## find

### Description
Fetches a single resource by its ID using a GET request. Returns the resource model instance.

### Method
GET

### Endpoint
`{base_url}{API_RESOURCE}/{resource_id}`

### Parameters
#### Path Parameters
- `resource_id` (str) - Required - The unique identifier of the resource to fetch.

#### Query Parameters
- `params` (QueryPairs) - Optional - Additional query parameters to include in the request.

#### Request Body
- `timeout` (Optional[httpx.Timeout]) - Optional - Timeout for the request, defaults to `DEFAULT_TIMEOUT` (10.0 seconds).

### Request Example
```python
plan = client.plans.find("plan_code_1")
```

### Response
#### Success Response
- Returns `_M` - A `RESPONSE_MODEL` instance parsed from the response.

#### Error Handling
- Throws `LagoApiError` on failure, including when the response body is empty under `ROOT_NAME` (raises a 500-class `LagoApiError` with detail `"Data is required to create instance of {response_model}"`).
```

--------------------------------

### Error handling example

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/customers.md

Catches LagoApiError when calling current_usage with a missing subscription. Prints status code, detail, and response.

```python
from lago_python_client.exceptions import LagoApiError

try:
    client.customers.current_usage("cus_1", external_subscription_id="sub_missing")
except LagoApiError as e:
    print(e.status_code, e.detail, e.response)
```

--------------------------------

### Usage example for subscription charges and alerts

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/subscriptions.md

Shows creating a subscription, retrieving lifetime usage, updating lifetime usage, creating an alert via nested client, and finding all charges of a subscription.

```python
from lago_python_client import Client
from lago_python_client.models.subscription import Subscription
from lago_python_client.models.alert import Alert

client = Client(api_key="sk_live_123")

sub = Subscription(
    external_customer_id="cus_1",
    plan_code="pro",
    billing_time="calendar",
)
created = client.subscriptions.create(sub)

usage = client.subscriptions.lifetime_usage(created.lago_id)
client.subscriptions.update_lifetime_usage(created.lago_id, external_historical_usage_amount_cents=1000)

# alerts via the nested client
client.subscriptions.alerts.create("sub_1", Alert(alert_type="usage_threshold", thresholds=...))

# charges of a subscription
charges = client.subscription_charges.find_all("sub_1")
```

--------------------------------

### Usage example for WebhookClient

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/taxes-webhooks.md

Shows how to create a Client, create a tax, create a webhook endpoint, and retrieve the public key for verifying webhook signatures.

```python
from lago_python_client import Client
from lago_python_client.models.tax import Tax
from lago_python_client.models.webhook_endpoint import WebhookEndpoint

client = Client(api_key="sk_live_123")

# taxes
tax = client.taxes.create(Tax(name="VAT 20%", code="vat_20", rate=20.0, applied_to_organization=True))

# webhook endpoints
endpoint = client.webhook_endpoints.create(
    WebhookEndpoint(webhook_url="https://example.com/lago", signature_algo="jwt", name="billing-hook")
)

# verify webhook signatures
public_key = client.webhooks.public_key()
```

--------------------------------

### Install lago-python-client with pip

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/README.md

Install the package from PyPI. Requires Python >3.6 (classifiers declare 3.7–3.11 support).

```bash
python -m pip install "lago-python-client"
```

--------------------------------

### Usage example for coupon and applied coupon operations

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/coupons.md

Shows creating a coupon, applying it to a customer, and terminating the applied coupon. Uses Client with api_key.

```python
from lago_python_client import Client
from lago_python_client.models.coupon import Coupon
from lago_python_client.models.applied_coupon import AppliedCoupon

client = Client(api_key="sk_live_123")

coupon = Coupon(
    name="Welcome 10%",
    code="welcome10",
    coupon_type="percentage",
    percentage_rate=10.0,
    frequency="once",
    reusable=False,
)
created = client.coupons.create(coupon)

applied = client.applied_coupons.create(
    AppliedCoupon(external_customer_id="cus_123", coupon_code="welcome10")
)

# terminate an applied coupon
client.applied_coupons.destroy("cus_123", applied.lago_id)
```

--------------------------------

### Usage example: create, estimate, void, download

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/credit-notes.md

Shows typical usage: create a credit note, estimate before creating, then void and download. Requires a valid API key.

```python
from lago_python_client import Client
from lago_python_client.models.credit_note import CreditNote, CreditNoteEstimate, Item, Items

client = Client(api_key="sk_live_123")

# create
note = CreditNote(invoice_id="inv_1", reason="other", credit_amount_cents=1000)
created = client.credit_notes.create(note)

# estimate before creating
est = client.credit_notes.estimate(
    CreditNoteEstimate(invoice_id="inv_1", items=Items(__root__=[Item(fee_id="fee_1")]))
)
print(est.max_creditable_amount_cents)

# void and download
client.credit_notes.void(created.lago_id)
downloaded = client.credit_notes.download(created.lago_id)
```

--------------------------------

### GET /invoices

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Lists all invoices.

```APIDOC
## GET /invoices

### Description
Lists all invoices.

### Method
GET

### Endpoint
/invoices

```

--------------------------------

### Usage example for activity and API logs

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/logs.md

Shows how to use client.activity_logs and client.api_logs to fetch recent activity and API request logs. Both clients are read-only.

```python
from lago_python_client import Client

client = Client(api_key="sk_live_123")

# recent activity
result = client.activity_logs.find_all({"per_page": 20})
for log in result["activity_logs"]:
    print(log.activity_type, log.resource_type, log.logged_at)

# API request logs (useful for debugging webhook/event delivery)
logs = client.api_logs.find_all({"http_status": "422"})
single = client.api_logs.find("req_123")
```

--------------------------------

### Usage example for create, batch_create, estimate_fees

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/events.md

Shows how to create a single event, batch events, and estimate fees using the EventClient. Uses Client with use_ingest_service=True for ingest URL.

```python
from lago_python_client import Client
from lago_python_client.models.event import Event, BatchEvent

client = Client(api_key="sk_live_123", use_ingest_service=True)

event = Event(
    transaction_id="evt_1",
    external_subscription_id="sub_1",
    code="page_view",
    properties={"url": "https://example.com/", "count": 1},
)
created = client.events.create(event)  # POST https://ingest.getlago.com/api/v1/events

# batch
client.events.batch_create(
    BatchEvent(events=[event, Event(transaction_id="evt_2", external_subscription_id="sub_1", code="page_view")])
)

# fee estimate
fees = client.events.estimate_fees(event)
for fee in fees["fees"]:
    print(fee.amount_cents)
```

--------------------------------

### GET /wallets

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Retrieves a list of wallets.

```APIDOC
## [GET] /wallets

### Description
Retrieves a list of wallets.

### Method
GET

### Endpoint
/wallets

### Response
#### Success Response (200)
- **wallet** (object) - The wallet data

#### Response Example
{
  "wallet": {}
}
```

--------------------------------

### Usage example: create, list, find, update, destroy

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/add-ons.md

Shows typical CRUD operations using the AddOnClient. Creates an add-on, lists with pagination, then finds, updates, and destroys it. Requires a valid API key.

```python
from lago_python_client import Client
from lago_python_client.models.add_on import AddOn

client = Client(api_key="sk_live_123")

# create
add_on = AddOn(code="priority-support", name="Priority Support", amount_cents=5000, amount_currency="USD")
created = client.add_ons.create(add_on)

# list with pagination
result = client.add_ons.find_all({"per_page": 25, "page": 2})
add_ons, meta = result["add_ons"], result["meta"]

# find, update, destroy
one = client.add_ons.find(created.lago_id)
updated = client.add_ons.update(AddOn(code="priority-support", amount_cents=7500), identifier=created.lago_id)
client.add_ons.destroy(created.lago_id)
```

--------------------------------

### GET /subscriptions

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Retrieves a list of subscriptions.

```APIDOC
## [GET] /subscriptions

### Description
Retrieves a list of subscriptions.

### Method
GET

### Endpoint
/subscriptions

### Response
#### Success Response (200)
- **subscription** (object) - The subscription data

#### Response Example
{
  "subscription": {}
}
```

--------------------------------

### Usage example for orders and order forms

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/orders.md

Shows how to use the client to find orders, execute an order on demand, and manage order forms (find, mark as signed, void). Requires an API key.

```python
from lago_python_client import Client
from lago_python_client.models.order import OrderExecute
from lago_python_client.models.order_form import OrderFormMarkAsSigned

client = Client(api_key="sk_live_123")

orders = client.orders.find_all()
order = client.orders.find("order_1")

# execute on demand
executed = client.orders.execute("order_1", OrderExecute(execution_mode="manual"))
print(executed.execution_record)

# order forms
forms = client.order_forms.find_all()
signed = client.order_forms.mark_as_signed(
    "of_1",
    OrderFormMarkAsSigned(signed_document="data:application/pdf;base64,..."),
)
client.order_forms.void("of_1")
```

--------------------------------

### GET /invoices/{id}

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Finds an invoice by its ID.

```APIDOC
## GET /invoices/{id}

### Description
Finds an invoice by its ID.

### Method
GET

### Endpoint
/invoices/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The invoice ID

```

--------------------------------

### find_all

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/base-client.md

Fetches a list of resources with optional query parameters. Returns a mapping containing the resource list and metadata.

```APIDOC
## find_all

### Description
Fetches a list of resources with optional query parameters. Returns a mapping containing the resource list and metadata.

### Method
GET

### Endpoint
`{base_url}{API_RESOURCE}`

### Parameters
#### Query Parameters
- `options` (QueryPairs) - Optional - Query parameters to filter or paginate the results.

#### Request Body
- `timeout` (Optional[httpx.Timeout]) - Optional - Timeout for the request, defaults to `DEFAULT_TIMEOUT` (10.0 seconds).

### Request Example
```python
result = client.invoices.find_all({"per_page": 10, "page": 1})
invoices, meta = result["invoices"], result["meta"]
```

### Response
#### Success Response
- Returns `Mapping[str, Any]` - A dict shaped `{API_RESOURCE: [RESPONSE_MODEL, ...], "meta": ...}`.
```

--------------------------------

### Usage example for quotes and quote versions

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/quotes.md

Shows how to find a quote, list its versions, approve a draft version with an optional expires_at, and clone a version for further edits.

```python
from lago_python_client import Client
from lago_python_client.models.quote import QuoteVersionApprove

client = Client(api_key="sk_live_123")

# find a quote and list its versions
quote = client.quotes.find("quote_1")
versions = client.quotes.versions("quote_1")
print(versions["quote_versions"])

# approve a draft version (generates the order form)
approved = client.quote_versions.approve("qv_1", QuoteVersionApprove(expires_at="2025-12-31T23:59:59Z"))
print(approved.status)

# clone for further edits
draft = client.quote_versions.clone("qv_1")
```

--------------------------------

### GET /events/{id}

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Finds an event by its ID.

```APIDOC
## GET /events/{id}

### Description
Finds an event by its ID.

### Method
GET

### Endpoint
/events/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The event ID

```

--------------------------------

### LoggingRateLimitObserver.__init__

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/rate-limit.md

Constructor for the LoggingRateLimitObserver class. Initializes the observer with configurable thresholds, logger, and log level for rate limit monitoring.

```APIDOC
## LoggingRateLimitObserver.__init__

### Description
Constructor for the LoggingRateLimitObserver class. Initializes the observer with configurable thresholds, logger, and log level for rate limit monitoring.

### Method
Constructor

### Parameters
- **thresholds** (Sequence[float]) - Optional - Usage fractions (0.0–1.0) that produce a log line. Default: (0.80, 0.90, 0.95)
- **logger** (Optional[logging.Logger]) - Optional - Logger to emit on; defaults to `lago_python_client.rate_limit`
- **level** (int) - Optional - Log level used when a threshold is crossed. Default: logging.WARNING

### Request Example
```python
observer = LoggingRateLimitObserver(
    thresholds=(0.80, 0.90, 0.95),
    logger=None,
    level=logging.WARNING,
)
```

### Response
No return value.
```

--------------------------------

### GET /subscriptions/{external_id}/charges

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Retrieves all charges for a subscription.

```APIDOC
## [GET] /subscriptions/{external_id}/charges

### Description
Retrieves all charges for a subscription.

### Method
GET

### Endpoint
/subscriptions/{external_id}/charges

### Parameters
#### Path Parameters
- **external_id** (string) - Required - The external ID of the subscription

### Response
#### Success Response (200)
- **charge** (object) - The charge data

#### Response Example
{
  "charge": {}
}
```

--------------------------------

### Usage example: update organization

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/organizations.md

Shows how to instantiate the client and update the organization with an Organization input model. The update call uses the singleton path and prints the updated name and default currency.

```python
from lago_python_client import Client
from lago_python_client.models.organization import Organization

client = Client(api_key="sk_live_123")

org = Organization(
    default_currency="USD",
    webhook_url="https://example.com/lago-webhooks",
    email="billing@acme.io",
    billing_configuration=OrganizationBillingConfiguration(invoice_grace_period=7),
)
updated = client.organizations.update(org)
print(updated.name, updated.default_currency)
```

--------------------------------

### GET /subscriptions/{subscription_id}/alerts

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Retrieves alerts for a subscription.

```APIDOC
## [GET] /subscriptions/{subscription_id}/alerts

### Description
Retrieves alerts for a subscription.

### Method
GET

### Endpoint
/subscriptions/{subscription_id}/alerts

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The ID of the subscription

#### Query Parameters
- **subscription_status** (string) - Optional - Filter by subscription status

### Response
#### Success Response (200)
- **alert** (object) - The alert data

#### Response Example
{
  "alert": {}
}
```

--------------------------------

### GET /plans/{plan_code}/charges

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Lists charges for a plan.

```APIDOC
## GET /plans/{plan_code}/charges

### Description
Lists charges for a plan.

### Method
GET

### Endpoint
/plans/{plan_code}/charges

### Parameters
#### Path Parameters
- **plan_code** (string) - Required - The plan code

```

--------------------------------

### TaxClient.find_all

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/taxes-webhooks.md

Retrieves a list of all taxes. Sends a GET request to the taxes endpoint.

```APIDOC
## [GET] /api/v1/taxes

### Description
Retrieves a list of all taxes.

### Method
GET

### Endpoint
/api/v1/taxes

### Response
#### Success Response (200)
- **taxes** (array) - List of tax objects.
- **meta** (object) - Pagination metadata.

#### Response Example
{
  "taxes": [
    {
      "name": "VAT",
      "code": "vat",
      "rate": 20.0,
      "description": "Value Added Tax",
      "applied_to_organization": true
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}
```

--------------------------------

### Lint with ruff format

Source: https://github.com/getlago/lago-python-client/blob/main/README.md

Format the codebase using ruff.

```bash
ruff format
```

--------------------------------

### CouponClient.find_all

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/coupons.md

Retrieves a list of all coupons. This method sends a GET request to the /api/v1/coupons endpoint.

```APIDOC
## [GET] /api/v1/coupons

### Description
Retrieves a list of all coupons.

### Method
GET

### Endpoint
/api/v1/coupons

### Parameters
#### Query Parameters
- `options` (object) - Optional - Query parameters for filtering and pagination.

### Request Example
GET /api/v1/coupons?page=1&per_page=10

### Response
#### Success Response (200)
- Returns `Mapping[str, Any]` - A dictionary containing a list of coupons and metadata.

#### Response Example
{
  "coupons": [
    {
      "name": "Welcome 10%",
      "code": "welcome10",
      "coupon_type": "percentage",
      "percentage_rate": 10.0,
      "frequency": "once",
      "reusable": false
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}
```

--------------------------------

### find_all

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/invoices.md

Retrieves a list of invoices. Sends a GET request to the invoices endpoint.

```APIDOC
## [GET] /api/v1/invoices

### Description
Retrieves a list of invoices.

### Method
GET

### Endpoint
/api/v1/invoices

### Parameters
#### Query Parameters
- `options` (QueryPairs) - Optional - Query parameters for filtering and pagination.

### Response
#### Success Response (200)
- Returns `Mapping[str, Any]` with structure `{"invoices": [...], "meta": ...}`

#### Response Example
```json
{
  "invoices": [],
  "meta": {}
}
```
```

--------------------------------

### create

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/base-client.md

Creates a new resource by POSTing the input object to the API resource endpoint. Returns the created resource model or None if no data is returned.

```APIDOC
## create

### Description
Creates a new resource by POSTing the input object to the API resource endpoint. Returns the created resource model or None if no data is returned.

### Method
POST

### Endpoint
`{base_url}{API_RESOURCE}`

### Parameters
#### Request Body
- `input_object` (BaseModel) - Required - The object to create, serialized as `{ROOT_NAME: input_object.dict(exclude_none=True)}`.
- `timeout` (Optional[httpx.Timeout]) - Optional - Timeout for the request, defaults to `DEFAULT_TIMEOUT` (10.0 seconds).

### Request Example
```python
client = Client(api_key="...")
created = client.add_ons.create(AddOn(code="support", amount_cents=1000, amount_currency="USD"))
```

### Response
#### Success Response
- Returns `Optional[_M]` - A `RESPONSE_MODEL` instance parsed from the response, or `None` when the response body has no data under `ROOT_NAME`.

#### Error Handling
- Throws `LagoApiError` / `LagoRateLimitError` for non-2xx responses.

### Response Example
```python
# custom timeout, error handling
try:
    result = client.customers.create(customer, timeout=httpx.Timeout(30.0))
except LagoRateLimitError as e:
    print(e.limit, e.remaining, e.reset)
```
```

--------------------------------

### CustomerClient.find_all

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/customers.md

Retrieves a list of all customers. Sends a GET request to the /api/v1/customers endpoint.

```APIDOC
## [GET] /api/v1/customers

### Description
Fetches all customers.

### Method
GET

### Endpoint
/api/v1/customers

### Parameters
#### Query Parameters
- `options` (QueryPairs) - Optional - Additional query parameters for filtering or pagination.

### Response
#### Success Response (200)
- Returns `Mapping[str, Any]` with keys `customers` and `meta`.

#### Response Example
```json
{
  "customers": [
    {
      "external_id": "string",
      "name": "string"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1
  }
}
```
```

--------------------------------

### Usage example for creating and evaluating billable metrics

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/billable-metrics.md

Shows how to create a billable metric and evaluate an expression without creating a metric. Uses Client with api_key and prints the created metric's lago_id and the evaluation result.

```python
from lago_python_client import Client
from lago_python_client.models.billable_metric import (
    BillableMetric,
    BillableMetricEvaluateExpression,
    BillableMetricEvaluateExpressionEvent,
)

client = Client(api_key="sk_live_123")

metric = BillableMetric(
    code="page_views",
    name="Page Views",
    aggregation_type="sum_agg",
    field_name="count",
)
created = client.billable_metrics.create(metric)
print(created.lago_id)

# evaluate an expression without creating a metric
result = client.billable_metrics.evaluate_expression(
    BillableMetricEvaluateExpression(
        expression="event.properties['amount'] * 100",
        event=BillableMetricEvaluateExpressionEvent(code="test", properties={"amount": 12.5}),
    )
)
print(result.value)
```

--------------------------------

### Create a plan with nested charges and filters

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/plans.md

Shows how to create a plan, add charges and fixed charges, and manage charge filters using the Lago Python client. Requires an API key and a billable metric ID for charges.

```python
from lago_python_client import Client
from lago_python_client.models.plan import Plan
from lago_python_client.models.charge import Charge
from lago_python_client.models.fixed_charge import FixedCharge

client = Client(api_key="sk_live_123")

plan = Plan(
    code="pro",
    name="Pro",
    interval="monthly",
    amount_cents=0,
    amount_currency="USD",
    pay_in_advance=True,
)
created = client.plans.create(plan)

# nested charges under the plan
client.plan_charges.create("pro", Charge(code="api_calls", charge_model="graduated", billable_metric_id="bm_1"))
client.plan_fixed_charges.create("pro", FixedCharge(code="setup_fee", add_on_code="setup", units=1.0))

# charge filters
client.plans.create_charge_filter("pro", "api_calls", ChargeFilter(values={"region": ["EU"]}))
filters = client.plans.find_all_charge_filters("pro", "api_calls")
```

--------------------------------

### GET /wallet_transactions/{id}/fundings

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Retrieves fundings for a wallet transaction.

```APIDOC
## [GET] /wallet_transactions/{id}/fundings

### Description
Retrieves fundings for a wallet transaction.

### Method
GET

### Endpoint
/wallet_transactions/{id}/fundings

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the wallet transaction

### Response
#### Success Response (200)
- **wallet_transaction_fundings** (object) - The funding data

#### Response Example
{
  "wallet_transaction_fundings": {}
}
```

--------------------------------

### NestedFindAllCommandMixin.find_all

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/base-client.md

Retrieves a list of resources under a nested path. Accepts variadic parent path segments.

```APIDOC
## find_all

### Description
Retrieves a list of resources under a nested path. Accepts variadic parent path segments.

### Method
find_all

### Signature
`(self, *parent_ids: str, options: QueryPairs = None, timeout: Optional[httpx.Timeout] = None) -> Mapping[str, Any]`

### Parameters
- **parent_ids** (str) - Required - Variadic parent path segments.
- **options** (QueryPairs) - Optional - Query parameters to filter or paginate the results.
- **timeout** (Optional[httpx.Timeout]) - Optional - Timeout for the request.

### Returns
Mapping[str, Any] - Index mapping of resources.
```

--------------------------------

### AddOn and AddOnResponse models

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/types.md

Input and response models for add-ons, used by AddOnClient (create, find, find_all, update, destroy).

```python
class AddOn(BaseModel):  # input
    name: Optional[str]; invoice_display_name: Optional[str]; code: Optional[str]
    amount_cents: Optional[int]; amount_currency: Optional[str]
    description: Optional[str]; tax_codes: Optional[List[str]]

class AddOnResponse(BaseResponseModel):  # response
    lago_id: str; name: str; code: str; amount_cents: int; amount_currency: str
    created_at: str; description: Optional[str]
    invoice_display_name: Optional[str]
    taxes: Optional[TaxesResponse]
```

--------------------------------

### GET /wallet_transactions/{id}/consumptions

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Retrieves consumptions for a wallet transaction.

```APIDOC
## [GET] /wallet_transactions/{id}/consumptions

### Description
Retrieves consumptions for a wallet transaction.

### Method
GET

### Endpoint
/wallet_transactions/{id}/consumptions

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the wallet transaction

### Response
#### Success Response (200)
- **wallet_transaction_consumptions** (object) - The consumption data

#### Response Example
{
  "wallet_transaction_consumptions": {}
}
```

--------------------------------

### GET /wallets/{wallet_id}/wallet_transactions

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Retrieves all wallet transactions for a wallet.

```APIDOC
## [GET] /wallets/{wallet_id}/wallet_transactions

### Description
Retrieves all wallet transactions for a wallet.

### Method
GET

### Endpoint
/wallets/{wallet_id}/wallet_transactions

### Parameters
#### Path Parameters
- **wallet_id** (string) - Required - The ID of the wallet

### Response
#### Success Response (200)
- **wallet_transactions** (array) - The wallet transactions

#### Response Example
{
  "wallet_transactions": []
}
```

--------------------------------

### BillingEntityClient usage example

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/billing-entities.md

Shows how to create, list, find, and update billing entities using the client. Requires an API key and imports BillingEntity and BillingEntityUpdate models.

```python
from lago_python_client import Client
from lago_python_client.models.billing_entity import BillingEntity, BillingEntityUpdate

client = Client(api_key="sk_live_123")

entity = BillingEntity(
    code="eu-entity",
    name="Lago EU",
    country="DE",
    default_currency="EUR",
    net_payment_term=30,
)
created = client.billing_entities.create(entity)

all_entities = client.billing_entities.find_all({"per_page": 50})

# read + update by id
found = client.billing_entities.find("eu-entity")
updated = client.billing_entities.update(
    BillingEntityUpdate(name="Lago EU Ltd.", country="DE"),
    identifier="eu-entity",
)

```

--------------------------------

### GET /subscriptions/{external_id}/fixed_charges

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Retrieves all fixed charges for a subscription.

```APIDOC
## [GET] /subscriptions/{external_id}/fixed_charges

### Description
Retrieves all fixed charges for a subscription.

### Method
GET

### Endpoint
/subscriptions/{external_id}/fixed_charges

### Parameters
#### Path Parameters
- **external_id** (string) - Required - The external ID of the subscription

### Response
#### Success Response (200)
- **fixed_charge** (object) - The fixed charge data

#### Response Example
{
  "fixed_charge": {}
}
```

--------------------------------

### Usage example: list, find, and update fees

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/fees.md

Shows how to use the FeeClient to list fees of an invoice, read a single fee, and update its payment status. Requires an API key and the Fee model. The find_all method returns a mapping with 'fees' and 'meta' keys.

```python
from lago_python_client import Client
from lago_python_client.models.fee import Fee

client = Client(api_key="sk_live_123")

# list fees of an invoice (query params per Lago API docs)
result = client.fees.find_all({"lago_invoice_id": "inv_1"})
fees, meta = result["fees"], result["meta"]

# read a single fee
fee = client.fees.find("fee_1")
print(fee.amount_cents, fee.payment_status)

# update payment status
updated = client.fees.update(Fee(payment_status="succeeded"), identifier="fee_1")
print(updated.payment_status)
```

--------------------------------

### GET /subscriptions/{external_id}/lifetime_usage

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Retrieves the lifetime usage of a subscription.

```APIDOC
## [GET] /subscriptions/{external_id}/lifetime_usage

### Description
Retrieves the lifetime usage of a subscription.

### Method
GET

### Endpoint
/subscriptions/{external_id}/lifetime_usage

### Parameters
#### Path Parameters
- **external_id** (string) - Required - The external ID of the subscription

### Response
#### Success Response (200)
- **lifetime_usage** (object) - The lifetime usage data

#### Response Example
{
  "lifetime_usage": {}
}
```

--------------------------------

### GET /plans/{plan_code}/fixed_charges

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/endpoints.md

Lists fixed charges for a plan.

```APIDOC
## GET /plans/{plan_code}/fixed_charges

### Description
Lists fixed charges for a plan.

### Method
GET

### Endpoint
/plans/{plan_code}/fixed_charges

### Parameters
#### Path Parameters
- **plan_code** (string) - Required - The plan code

```

--------------------------------

### Client Constructor

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/client.md

Initializes the top-level Lago API client with authentication, base URLs, and rate-limit configuration. This is the entry point for all API interactions.

```APIDOC
## Client Constructor

### Description
Creates a new Client instance that holds the API key, base URLs, and rate-limit configuration. It exposes lazily-created collection clients for each Lago API resource.

### Method
Constructor

### Signature
```python
Client(
    api_key: str = "",
    api_url: str = "",
    use_ingest_service: bool = False,
    ingest_api_url: str = "",
    max_retries: int = 3,
    retry_on_rate_limit: bool = True,
    on_rate_limit_info: Optional[RateLimitCallback] = None
) -> None
```

### Parameters
- **api_key** (str) - Optional - Bearer token sent in the `Authorization` header. Default: `""`.
- **api_url** (str) - Optional - Custom API origin (self-hosted Lago); when empty, `Client.BASE_URL` is used. Default: `""`.
- **use_ingest_service** (bool) - Optional - When `True`, event ingestion goes to the dedicated ingest origin instead of the API origin. Default: `False`.
- **ingest_api_url** (str) - Optional - Custom ingest origin; when empty (and `use_ingest_service` is true) `Client.BASE_INGEST_URL` is used. Default: `""`.
- **max_retries** (int) - Optional - Max retry attempts on HTTP 429 (forwarded to `RateLimitRetryConfig`). Default: `3`.
- **retry_on_rate_limit** (bool) - Optional - Auto-retry on 429 (forwarded to `RateLimitRetryConfig`). Default: `True`.
- **on_rate_limit_info** (Optional[RateLimitCallback]) - Optional - Callback invoked after every response with parsed `x-ratelimit-*` headers (forwarded to `RateLimitRetryConfig`). Default: `None`.

### Notes
- `RateLimitCallback` is defined as `Callable[[RateLimitInfo], None]` in `lago_python_client/services/rate_limit.py`.
- The constructor stores `api_key`, `api_url`, `use_ingest_service`, `ingest_api_url` as public attributes and builds `self.rate_limit_retry_config` from the rate-limit arguments.

### Class Constants
- `BASE_URL` = `"https://api.getlago.com/"` - Default cloud API origin.
- `BASE_INGEST_URL` = `"https://ingest.getlago.com/"` - Default event-ingestion origin.
- `API_PATH` = `"api/v1/"` - Path prefix appended to either origin.
```

--------------------------------

### find_all

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/subscriptions.md

Retrieves a list of subscriptions. Sends a GET request to the subscriptions endpoint.

```APIDOC
## [GET] /api/v1/subscriptions

### Description
Retrieves a list of subscriptions.

### Method
GET

### Endpoint
/api/v1/subscriptions

### Parameters
#### Query Parameters
- `options` (QueryPairs) - Optional - Additional query parameters.

### Response
#### Success Response (200)
- Returns `Mapping[str, Any]` with keys `subscriptions` and `meta`.

#### Response Example
```json
{
  "subscriptions": [],
  "meta": {}
}
```
```

--------------------------------

### find

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/plans.md

Retrieves a specific plan by its ID using a GET request. The response is a PlanResponse.

```APIDOC
## [GET] /api/v1/plans/{resource_id}

### Description
Retrieves a specific plan by its ID using a GET request. The response is a PlanResponse.

### Method
GET

### Endpoint
/api/v1/plans/{resource_id}

### Parameters
#### Path Parameters
- **resource_id** (string) - Required - The ID of the plan to retrieve.

#### Query Parameters
- **params** (QueryPairs) - Optional - Additional query parameters.
- **timeout** (Optional[httpx.Timeout]) - Optional - Request timeout.

### Response
#### Success Response (200)
- **PlanResponse** - The requested plan.

#### Response Example
{
  "plan": {
    "lago_id": "string",
    "name": "string",
    "code": "string"
  }
}
```

--------------------------------

### Run tests with pytest

Source: https://github.com/getlago/lago-python-client/blob/main/README.md

Execute the test suite.

```bash
pytest
```

--------------------------------

### PaymentClient.find_all

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/payments.md

Retrieves a list of all payments. Sends a GET request to the payments endpoint.

```APIDOC
## [GET] /api/v1/payments

### Description
Retrieves a list of all payments.

### Method
GET

### Endpoint
/api/v1/payments

### Parameters
#### Query Parameters
- **options** (object) - Optional - Query parameters for filtering, pagination, etc.

### Response
#### Success Response (200)
- **payments** (array) - List of payment objects.
- **meta** (object) - Pagination metadata.

#### Response Example
{
  "payments": [
    {
      "lago_id": "...",
      "invoice_id": "123456",
      "amount_cents": 1000,
      "reference": "Payment for invoice 123456",
      "paid_at": "2023-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}
```

--------------------------------

### create

Source: https://github.com/getlago/lago-python-client/blob/main/_autodocs/api-reference/plans.md

Creates a new plan by sending a POST request to the plans endpoint. The input object should be a Plan model, and the response is a PlanResponse.

```APIDOC
## [POST] /api/v1/plans

### Description
Creates a new plan by sending a POST request to the plans endpoint. The input object should be a Plan model, and the response is a PlanResponse.

### Method
POST

### Endpoint
/api/v1/plans

### Parameters
#### Request Body
- **input_object** (BaseModel) - Required - The Plan object to create.
- **timeout** (Optional[httpx.Timeout]) - Optional - Request timeout.

### Request Example
{
  "plan": {
    "name": "string",
    "code": "string"
  }
}

### Response
#### Success Response (200)
- **PlanResponse** - The created plan.

#### Response Example
{
  "plan": {
    "lago_id": "string",
    "name": "string",
    "code": "string"
  }
}
```
Tokens:
Raw