Customers.md

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

Customer API reference · All methods