Customers Guide

Learn how to work with customer data via the Pixlpay API.

List Customers

Retrieve all customers with optional filtering and pagination.

curl "https://yourstore.pixlpay.net/api/external/v1/customers" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters

Parameter	Type	Description
search	string	Search by name or email
email	string	Filter by email address
registered_after	date	Customers registered after this date
registered_before	date	Customers registered before this date
sort_by	string	Sort field: created_at, name, email
sort_order	string	asc or desc
page	integer	Page number
per_page	integer	Items per page (max 100)

Example with Filters

curl "https://yourstore.pixlpay.net/api/external/v1/customers?search=player&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "success": true,
  "data": [
    {
      "id": 45,
      "name": "PlayerOne",
      "email": "player@example.com",
      "orders_count": 12,
      "support_tickets_count": 2,
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-20T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 68
  }
}

Get Single Customer

Retrieve detailed information about a specific customer including statistics and recent orders.

curl "https://yourstore.pixlpay.net/api/external/v1/customers/45" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "success": true,
  "data": {
    "id": 45,
    "name": "PlayerOne",
    "email": "player@example.com",
    "orders_count": 12,
    "support_tickets_count": 2,
    "orders": [
      {
        "id": 123,
        "order_number": "ORD-2025-00123",
        "total": "29.99",
        "status": "completed",
        "created_at": "2025-01-20T14:30:00Z"
      },
      {
        "id": 100,
        "order_number": "ORD-2025-00100",
        "total": "14.99",
        "status": "completed",
        "created_at": "2025-01-15T10:00:00Z"
      }
    ],
    "statistics": {
      "total_spent": "359.88",
      "total_orders": 12,
      "average_order_value": "29.99",
      "last_order_date": "2025-01-20T14:30:00Z"
    },
    "created_at": "2025-01-10T08:00:00Z",
    "updated_at": "2025-01-20T14:30:00Z"
  }
}

Customer Statistics

The statistics object provides valuable insights:

Field	Description
total_spent	Lifetime spending
total_orders	Number of completed orders
average_order_value	Average order amount
last_order_date	Most recent purchase

Common Use Cases

Find Customer by Email

async function findCustomerByEmail(email) {
  const response = await fetch(
    `${BASE_URL}/customers?email=${encodeURIComponent(email)}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  const data = await response.json();
  return data.data[0] || null;
}

Get Top Customers

async function getTopCustomers(limit = 10) {
  // Get all customers and sort by total spent
  const customers = await getAllCustomers();

  // Get detailed stats for each
  const withStats = await Promise.all(
    customers.map(async (c) => {
      const detail = await getCustomer(c.id);
      return {
        ...c,
        total_spent: parseFloat(detail.statistics.total_spent)
      };
    })
  );

  // Sort by total spent
  return withStats
    .sort((a, b) => b.total_spent - a.total_spent)
    .slice(0, limit);
}

Sync Customers to CRM

async function syncCustomersToCRM() {
  const customers = await pixlpay.getCustomers();

  for (const customer of customers) {
    const detail = await pixlpay.getCustomer(customer.id);

    await crm.upsertContact({
      email: customer.email,
      name: customer.name,
      total_spent: detail.statistics.total_spent,
      total_orders: detail.statistics.total_orders,
      last_purchase: detail.statistics.last_order_date,
      source: 'pixlpay',
    });
  }
}

Customer Segmentation

async function segmentCustomers() {
  const customers = await getAllCustomersWithStats();

  return {
    vip: customers.filter(c => parseFloat(c.total_spent) > 500),
    active: customers.filter(c => {
      const lastOrder = new Date(c.last_order_date);
      const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
      return lastOrder > thirtyDaysAgo;
    }),
    dormant: customers.filter(c => {
      const lastOrder = new Date(c.last_order_date);
      const ninetyDaysAgo = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
      return lastOrder < ninetyDaysAgo;
    }),
  };
}

Required Scopes

Endpoint	Required Scope
GET /customers	customers:read
GET /customers/:id	customers:read