Customers - Zahlo Merchant Developer Docs

A customer represents the person or account that owns payment history, invoices, subscriptions, and reusable payment methods. Keep your internal account ID in metadata and use the Zahlo customer ID as the foreign key in payment resources.

Create a customer

const response = await fetch("https://merchant.zahlo.eu/api/v1/customers", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.ZAHLO_API_KEY,
    "Idempotency-Key": "customer-account-1001",
  },
  body: JSON.stringify({
    email: "buyer@example.com",
    name: "Example Buyer",
    metadata: { accountId: "account_1001" },
  }),
});
const customer = await response.json();

Use an idempotency key derived from your own account creation operation. Do not use email as the only identifier; customers can change it and one customer may own multiple orders or subscriptions.

Use customer context

Pass customerId when creating a payment intent, checkout session, subscription, or portal session. Retrieve the customer on the server before changing billing state and verify ownership in your application.

Privacy and deletion

Collect only fields needed for the stated payment or billing flow. Keep personal data out of metadata and logs. When an account is deleted, remove your local references according to your retention policy and revoke active portal or client sessions.