Customers
Keep a Vatly customer ID alongside your own user or company. Customers hold billing
identity; a shared email or customer ID is not proof that someone owns an order.
Pass a configured VatlyClient to the functions below; see setup.
Create, retrieve and update
from vatly import RequestOptions, VatlyClient
from vatly.models import CreateCustomerRequest
def example(client: VatlyClient):
customer = client.customers.create(
CreateCustomerRequest(email="buyer@example.com", name="Alex"),
options=RequestOptions(idempotency_key="signup:user-42"),
)
saved = client.customers.get(customer.id)
updated = client.customers.update(saved.id, {"name": "Alex Morgan"})
return updated.id, updated.email
| Create/update parameter | Type | Purpose |
|---|---|---|
email | string | Required on create; optional on update |
name | string or null | Optional name; null clears it on update |
metadata | object | Optional custom data on create; not an update field |
Update changes name/email, not invoice addresses. Use the hosted billing flows for address changes. Keep the same idempotency key when retrying the same signup.
Find by email and read subscriptions
from vatly import VatlyClient
def example(client: VatlyClient):
customers = list(client.customers.list_all({"email": "buyer@example.com", "limit": 25}))
subscriptions = list(client.customers.list_all_subscriptions("customer_example"))
return customers, subscriptions
Email lookup returns zero or more customers within the API key's storefront and
mode. General list filters are limit (1–100), startingAfter, or endingBefore;
do not send both cursors. list() returns one page; list_all() yields resources.
Open the hosted portal
from vatly import VatlyClient
def example(client: VatlyClient):
session = client.customers.create_portal_session(
"customer_example", {"returnUrl": "https://app.example.com/billing"}
)
return session.url
Authorize the customer before calling this. Redirect the browser to the returned
single-use URL; never cache or log it. returnUrl is optional; use {} for no
return link. It does not automatically redirect the customer back.
| Response field | Python type | Meaning |
|---|---|---|
id, email | str | Customer identity |
name | str or None | Display name |
created_at, testmode | datetime, bool | Creation time and mode |
metadata, links | model objects | Custom data and resource links |
Portal url, expires_at | str, datetime | Temporary entry URL and expiry |