Skip to main content

Customer API

Complete API reference for customer management operations.

Base Endpoint​

/api/v1/customers

List Customers​

Get a paginated list of customers.

GET /api/v1/customers

Query Parameters​

ParameterTypeDescription
pageintegerPage number (default: 1)
limitintegerItems per page (default: 20, max: 100)
sortstringSort field and direction (e.g., created_at:desc)
filter[tier]stringFilter by membership tier
filter[status]stringFilter by status (active, inactive)
searchstringFull-text search
date_fromstringFilter from date (ISO 8601)
date_tostringFilter to date (ISO 8601)

Example Request​

GET /api/v1/customers?page=1&limit=20&filter[tier]=gold&sort=created_at:desc
Authorization: Bearer YOUR_ACCESS_TOKEN

Example Response​

{
  "data": [
    {
      "id": "cus_12345",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "tier": "gold",
      "points_balance": 5000,
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

Get Customer​

Retrieve a specific customer by ID.

GET /api/v1/customers/{customer_id}

Path Parameters​

ParameterTypeDescription
customer_idstringCustomer ID

Query Parameters​

ParameterTypeDescription
includestringComma-separated list of related resources (points, tier, rewards, campaigns)

Example Request​

GET /api/v1/customers/cus_12345?include=points,tier,rewards
Authorization: Bearer YOUR_ACCESS_TOKEN

Example Response​

{
  "data": {
    "id": "cus_12345",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "date_of_birth": "1990-05-15",
    "gender": "male",
    "tier": {
      "id": "tier_gold",
      "name": "Gold",
      "level": 3
    },
    "points": {
      "balance": 5000,
      "lifetime_earned": 15000,
      "lifetime_redeemed": 10000
    },
    "rewards": [
      {
        "id": "rew_123",
        "name": "10% Discount Voucher",
        "status": "available"
      }
    ],
    "wechat": {
      "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
      "unionid": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M",
      "nickname": "John",
      "avatar": "https://..."
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:22:00Z"
  }
}

Create Customer​

Create a new customer.

POST /api/v1/customers

Request Body​

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "date_of_birth": "1990-05-15",
  "gender": "male",
  "address": {
    "street": "123 Main St",
    "city": "Shanghai",
    "postal_code": "200000"
  },
  "language": "zh-CN",
  "wechat": {
    "code": "WECHAT_AUTH_CODE"
  }
}

Example Response​

{
  "data": {
    "id": "cus_12345",
    "name": "John Doe",
    "email": "john@example.com",
    "tier": "bronze",
    "points_balance": 0,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Update Customer​

Update customer information.

PATCH /api/v1/customers/{customer_id}

Path Parameters​

ParameterTypeDescription
customer_idstringCustomer ID

Request Body​

{
  "name": "John Smith",
  "phone": "+1234567891",
  "address": {
    "street": "456 Oak Ave",
    "city": "Shanghai"
  }
}

Example Response​

{
  "data": {
    "id": "cus_12345",
    "name": "John Smith",
    "email": "john@example.com",
    "phone": "+1234567891",
    "updated_at": "2024-01-20T15:00:00Z"
  }
}

Update Customer Tier​

Update customer membership tier.

PATCH /api/v1/customers/{customer_id}/tier

Request Body​

{
  "tier": "gold",
  "reason": "Points threshold reached"
}

Link WeChat account to customer profile.

POST /api/v1/customers/{customer_id}/wechat/link

Request Body​

{
  "code": "WECHAT_AUTH_CODE",
  "app_id": "YOUR_WECHAT_APP_ID"
}

Get Customer Segments​

Get segments that a customer belongs to.

GET /api/v1/customers/{customer_id}/segments

Example Response​

{
  "data": [
    {
      "id": "seg_123",
      "name": "Gold Members",
      "type": "manual"
    },
    {
      "id": "seg_456",
      "name": "High Value Customers",
      "type": "ai"
    }
  ]
}

Get Customer Interaction History​

Get customer interaction timeline.

GET /api/v1/customers/{customer_id}/interactions

Query Parameters​

ParameterTypeDescription
typestringFilter by interaction type (purchase, visit, click, etc.)
date_fromstringFilter from date
date_tostringFilter to date

Example Response​

{
  "data": [
    {
      "id": "int_123",
      "type": "purchase",
      "channel": "pos",
      "description": "Purchase at Store A",
      "amount": 500.00,
      "points_earned": 50,
      "created_at": "2024-01-20T14:00:00Z"
    },
    {
      "id": "int_456",
      "type": "campaign_joined",
      "channel": "wechat",
      "description": "Joined Summer Sale Campaign",
      "created_at": "2024-01-19T10:00:00Z"
    }
  ]
}

Error Responses​

Customer Not Found​

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "Customer not found"
  }
}

Validation Error​

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": [
      {
        "field": "email",
        "message": "Email is required"
      }
    ]
  }
}