Customers

Customers represent your end users who purchase products through Vatly.

The Customer Resource

Below you'll find all properties for the Vatly Customer resource.

Properties

Create a customer

POST /v1/customers

Create a new customer.

Required attributes

Optional attributes

$customer = $vatly->customers->create([
    'email' => 'john@example.com',
    'name' => 'John Doe',
    'metadata' => [
        'user_id' => '12345',
    ],
]);

echo $customer->id;  // customer_abc123

Retrieve a customer

GET /v1/customers/:id

Retrieve a customer by their ID.

$customer = $vatly->customers->get('customer_abc123');

echo $customer->email;
echo $customer->name;

Update a customer

PATCH /v1/customers/:id

Update a customer's identity fields. Only name and email may be changed, and both are optional — send whichever you want to update. Billing-address details (company name, tax ID, street, city, country, etc.) are not editable here; amend those through the hosted billing-update flow.

Optional attributes

$customer = $vatly->customers->update('customer_abc123', [
    'name' => 'Jane Doe',
    'email' => 'jane@example.com',
]);

echo $customer->name; // Jane Doe

If you already have a Customer resource instance:

$customer->update([
    'name' => 'Jane Doe',
]);

The SDK generates an idempotency key automatically for the PATCH request, or you can set your own via $vatly->setIdempotencyKey(...) beforehand.

List all customers

GET /v1/customers

Retrieve a paginated list of all your customers.

Optional attributes

$customers = $vatly->customers->list();

foreach ($customers as $customer) {
    echo $customer->email;
}

// Pagination
$customers = $vatly->customers->list([
    'limit' => 25,
    'startingAfter' => 'customer_last_id',
]);

Recover a customer by email

GET /v1/customers?email=...

Look up customers by email address — the way back to a customer id you no longer have (after a re-sync or reset). The address is canonicalized before matching, exactly as on write. An address can be held by more than one customer, so this always returns a (possibly empty) collection.

$customers = $vatly->customers->listByEmail('john@example.com');

if (count($customers) > 0) {
    echo $customers[0]->id; // customer_abc123
}

You can also recover in a single call by creating the customer again: create is get-or-create on the email, so posting a known address returns the existing customer (200) rather than a validation error, while a genuinely new address is created (201). Either way you get the customer back:

$customer = $vatly->customers->create(['email' => 'john@example.com']);

echo $customer->id; // the existing customer id, if the email was already known

Create a customer portal session

POST /v1/customers/:id/portal-sessions

Create a short-lived, single-use link that sends an authenticated customer straight to your storefront in Vatly's hosted portal (where they can manage their subscriptions, billing details, and invoices). The session is locked to the customer, storefront, merchant, and live/test mode of the API token: the customer lands directly in that one storefront's portal — never a storefront picker or any other store. If your account has multiple storefronts, each API token mints portal links for its own store.

Redirect the customer's browser to the returned url. It expires after roughly 15 minutes and can be consumed once, so create a fresh one per visit. The link is credential-bearing — do not cache or log it.

Optional attributes

The returned PortalSession has three properties:

$session = $vatly->customers->createPortalSession('customer_abc123', [
    'returnUrl' => 'https://yourapp.com/account/billing',
]);

// Redirect the customer's browser to the hosted portal.
header('Location: ' . $session->url);

The body is optional — omit it to create a session without a return link:

$session = $vatly->customers->createPortalSession('customer_abc123');