Customers

Access merchant customer data using client.customers — list and get individual customer records.

client.customers provides read access to the merchant's customer base. All operations require the read:customers scope.

Required Scopes

Operation	Required Scope
`list`, `get`	`read:customers`

HTTP Mapping

Method	HTTP Verb	Path
`list(params?)`	GET	`/customers`
`get(id)`	GET	`/customers/:id`

Methods

list

Retrieve a paginated list of customers.

const { data, pagination } = await client.customers.list({
  page: 1,
  per_page: 25,
});

data.forEach((customer) => {
  console.log(`${customer.name} — ${customer.email}`);
});

console.log(`Page 1 of ${pagination.pages}`);

get

Retrieve a single customer by their ID.

const customer = await client.customers.get("365047281936");

console.log(customer.name);
console.log(customer.email);
console.log(customer.phone);

Data Privacy Considerations

Customer data is sensitive. When building plugins that access client.customers:

Only request read:customers if your plugin genuinely needs it — the scope appears on the merchant's install permission screen.
Do not store raw customer PII (emails, phone numbers) in your own database unless it is strictly necessary for your plugin's functionality.
Follow the data retention and deletion policies documented in the Publishing guidelines.
Respond to app.uninstalled webhook events by deleting any stored customer data for that merchant.

Error Handling

import { NotFoundError, AuthorizationError } from "@whatalo/plugin-sdk";

try {
  const customer = await client.customers.get("999999999999");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(`Customer not found: ${error.resourceId}`);
  } else if (error instanceof AuthorizationError) {
    // Plugin does not have read:customers scope
    console.log(`Missing scope: ${error.requiredScope}`);
  } else {
    throw error;
  }
}

See Errors & Rate Limits for the full error class reference.