Customers

A Customer represents one end-user of your business — the person you charge, subscribe, refund, or invoice. Customers are the parent of payment instruments, orders, subscriptions, and wallets, all of which are reachable as helper methods on this resource.

Namespace: client.customers.

Methods

`create`

customer = client.customers.create(
    first_name="Ada",
    last_name="Lovelace",
    email="ada@example.com",
    phone="+15551234567",
    personal_address={
        "line1": "1 Babbage St",
        "city": "London",
        "country": "GB",
    },
    tags={"plan": "founder"},
    idempotency_key="customer-ada-2025-01-01",
)

Returns: Customer. Only first_name and last_name are required.

`update`

customer = client.customers.update(
    "cus_123",
    phone="+15559999999",
    tags={"plan": "growth"},
)

Accepts arbitrary fields via **kwargs and PATCHes them. Returns the updated Customer.

`retrieve`

customer = client.customers.retrieve("cus_123")

`list`

customers = client.customers.list(limit=50, offset=0)

# Look up specific customers by ID
batch = client.customers.list(ids=["cus_1", "cus_2"])

Returns list[Customer]. See Pagination for offset walking patterns.

`payment_instruments`

instruments = client.customers.payment_instruments("cus_123")

Returns list[PaymentInstrument] for the customer.

`orders`

orders = client.customers.orders("cus_123", limit=20)

Returns list[Order].

`subscriptions`

page = client.customers.subscriptions("cus_123", status="active", limit=20)
print(page["total"])
for sub in page["data"]:           # list[Subscription]
    print(sub.id, sub.status)

Returns the paginated envelope { data, total, limit, offset } as a plain dict — data contains Subscription models.

`wallets`

wallets = client.customers.wallets("cus_123")

Returns list[Wallet].

Object shape

The Customer model surfaces the most common fields with type hints; unknown fields are still accessible because EasyModel allows extras.

Field	Type	Notes
`id`	`str`	Always present.
`created_at`	`str \| None`	ISO-8601.
`updated_at`	`str \| None`	ISO-8601.
`type`	`str \| None`	Identity type (e.g. `"PERSONAL"`).
`application`	`str \| None`	Easy Labs application ID.
`identity_roles`	`list[str] \| None`
`entity`	`dict[str, Any] \| None`	Structured personal/business profile.
`tags`	`dict[str, Any] \| None`	Free-form metadata you set.

The full canonical shape lives in the Easy Labs API reference.

Examples

Idempotent create from a webhook handler

def on_signup(user, raw_request):
    customer = client.customers.create(
        first_name=user.first_name,
        last_name=user.last_name,
        email=user.email,
        idempotency_key=f"signup-{user.id}",   # safe to retry
    )
    user.update(easy_customer_id=customer.id)

List + walk every customer

PAGE = 100
offset = 0
while True:
    page = client.customers.list(limit=PAGE, offset=offset)
    if not page:
        break
    for c in page:
        print(c.id, c.email)
    if len(page) < PAGE:
        break
    offset += PAGE

Aggregate a customer's payments

instruments = client.customers.payment_instruments("cus_123")
orders = client.customers.orders("cus_123")
total_paid = sum(o.total or 0 for o in orders)
print(f"{len(instruments)} cards, ${total_paid / 100:.2f} lifetime")

Customers

On this page