Customers
Customers represent the end users who purchase products through Vatly.
For all fields and options, see the Customers API reference. The OpenAPI spec is also available for tooling.
The Customer resource
| Name | Type | Description |
|---|---|---|
id | string | Unique identifier for the customer (customer_…). |
resource | string | Always customer. |
email | string | Customer's email address (ASCII / Punycode domain). |
metadata | object | null | Your custom key/value metadata. |
createdAt | string | Creation timestamp (ISO 8601). |
testmode | boolean | Whether this is a test customer. |
Create a customer
POST /v1/customers
Required attributes
| Name | Type | Description |
|---|---|---|
email | string | The customer's email address. |
Optional attributes
| Name | Type | Description |
|---|---|---|
metadata | object | Custom key/value metadata. |
const customer = await vatly.customers.create({
email: "ada@example.com",
metadata: { plan: "pro" },
});
Unicode domains are accepted directly; Vatly lowercases the local part and canonicalizes the domain to lowercase Punycode. Creating an already-known email returns the existing customer unchanged. To encode a domain yourself, optionally use:
import { encodeEmail } from "@getvatly/sdk";
encodeEmail("user@bücher.de"); // → "user@xn--bcher-kva.de"
Retrieve a customer
GET /v1/customers/{customerId}
const customer = await vatly.customers.get("customer_abc123");
Update identity and open the hosted portal
await vatly.customers.update("customer_abc123", { name: "Ada", email: "ada@example.com" });
const session = await vatly.customers.createPortalSession("customer_abc123", {
returnUrl: "https://yourapp.com/account",
});
// Redirect the customer's browser to session.url. It is short-lived and single-use.
Updates accept name/email, not billing addresses. Portal settings are optional;
returnUrl must be an absolute HTTPS URL without credentials, sent in the JSON
body (not query params), at most 2,048 UTF-8 bytes. Authenticate your own customer
before issuing a portal session, and never log or persist its credential URL.
List customers
GET /v1/customers
const page = await vatly.customers.list({ limit: 25 });
for await (const customer of vatly.customers.listAll()) {
// ...
}
A customer's subscriptions
GET /v1/customers/{customerId}/subscriptions
// One page:
const page = await vatly.customers.listSubscriptions("customer_abc123", { limit: 10 });
// Every subscription:
for await (const sub of vatly.customers.listAllSubscriptions("customer_abc123")) {
// ...
}
// A single nested subscription:
const sub = await vatly.customers.getSubscription("customer_abc123", "subscription_abc123");