Skip to main content

Customers API

The Customers API allows you to manage and retrieve customer information for your store. This API is designed for server-side integrations and enables you to look up customers, list them with filtering options, and access customer-specific data like shopping carts.

Overview​

The Customers API provides endpoints to:

  • Retrieve customer information by ID, phone number, or email address
  • List all customers with pagination and filtering
  • Access customer shopping cart data
  • Search and filter customers based on various criteria

All customer operations are scoped to your store, ensuring data isolation and security.

Use Cases​

Customer Lookup and Verification​

When a customer contacts support or makes a purchase through external channels, you can quickly retrieve their information using their phone number or email:

// Look up customer by phone number
const customer = await vesuvioPay.customers.getByPhone('+1234567890');

// Look up customer by email
const customer = await vesuvioPay.customers.getByEmail('customer@example.com');

Customer Management Dashboard​

Build administrative interfaces that display customer lists with filtering and pagination:

// Get paginated customer list
const customers = await vesuvioPay.customers.list({
  limit: 50,
  offset: 0,
  searchTerm: 'john'
});

Order Processing Integration​

When processing orders from external platforms, retrieve customer cart information to understand their shopping session:

// Get customer's current cart
const cart = await vesuvioPay.customers.getCart(customerId);

CRM Synchronization​

Sync customer data between VesuvioPay and your CRM system to maintain a unified customer database across platforms.

Authentication​

Private API Key Required

All Customers API endpoints require authentication using a Private API Key. Never expose your private key in client-side code or public repositories.

Include your private API key in the request header:

X-API-Key: your_private_api_key_here

Private API keys have full access to your store's data and should be stored securely in environment variables or secret management systems.

Key Concepts​

Customer Identifiers​

Customers can be uniquely identified using three different methods:

  1. Customer ID: A GUID that serves as the internal unique identifier
  2. Phone Number: The customer's verified phone number (E.164 format recommended)
  3. Email Address: The customer's email address

Choose the identifier that best fits your integration workflow.

Store Scoping​

All customer queries are automatically scoped to your store based on the API key used. You cannot access customers from other stores, ensuring data privacy and security.

Pagination​

Customer list endpoints support pagination through limit and offset parameters:

  • limit: Maximum number of customers to return (1-100, default: 50)
  • offset: Number of customers to skip (for page navigation)

Customer Data Structure​

Customer objects include:

  • Basic Information: Name, email, phone number
  • Verification Status: Whether phone/email are verified
  • Timestamps: Created date, last updated date
  • Metadata: Custom fields and additional attributes

Cart Access​

Each customer has an associated shopping cart. You can retrieve the customer's current cart through the customer endpoints, which shows:

  • Cart items with product details
  • Quantities and pricing
  • Store-specific cart data
  • Cart status and timestamps

Response Format​

All customer endpoints return data in a consistent JSON format:

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "customer@example.com",
    "phoneNumber": "+1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "isPhoneVerified": true,
    "isEmailVerified": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z"
  }
}

Error Handling​

Common error scenarios:

  • 404 Not Found: Customer with specified identifier doesn't exist
  • 401 Unauthorized: Missing or invalid API key
  • 403 Forbidden: API key doesn't have access to the specified store
  • 400 Bad Request: Invalid parameters (e.g., malformed phone number)

See the Error Handling guide for detailed error response formats.

Rate Limiting​

Customer API endpoints are subject to rate limiting. See the Rate Limiting documentation for current limits and best practices.

Best Practice

Cache customer data in your application when possible to reduce API calls and improve performance. Implement webhook listeners to receive real-time updates when customer data changes.

Data Privacy​

Customer data is sensitive and must be handled according to privacy regulations (GDPR, CCPA, etc.):

  • Only request customer data when necessary for business operations
  • Implement appropriate access controls in your application
  • Follow data retention policies
  • Respect customer consent and privacy preferences

Next Steps​

  • Review specific endpoint documentation in the API reference below
  • Set up webhooks to receive customer events
  • Integrate with the Orders API for complete order management

Interactive API Reference​

Detailed endpoint documentation is auto-generated from our OpenAPI specification. See the interactive API reference below for complete request/response schemas, example requests, and the ability to test endpoints directly.