Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway at /v1/commerce/*.

Customers API

Manage customer profiles, loyalty programs, and customer-initiated orders.

Authentication Required

All endpoints require a valid Bearer token. See Authentication for details.

Overview

Attribute	Value
Base Path	/api/v1/customers
Authentication	Bearer Token
Required Roles	customer, customer_support, restaurant_manager, tenant_admin, platform_admin, system_admin, super_admin

Endpoints

List Customers

Retrieve a paginated list of customers with optional filtering.

GET /api/v1/customers

Query Parameters

Parameter	Type	Description
search	string	Search by name, email, or phone
email	string	Filter by exact email address
phone	string	Filter by phone number
loyalty_tier	string	Filter by tier: bronze, silver, gold, platinum
segment	string	Filter by customer segment
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 20, max: 100)

Response

{
  "data": [
    {
      "id": "cust_abc123",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "loyalty_tier": "gold",
      "loyalty_points": 1250,
      "total_orders": 45,
      "total_spent": 1234.56,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150
  }
}

---

Create Customer

Create a new customer profile.

POST /api/v1/customers

Request Body

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "birthday": "1990-05-15",
  "preferences": {
    "dietary_restrictions": ["vegetarian"],
    "favorite_items": []
  }
}

Response 201 Created

{
  "id": "cust_abc123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "loyalty_tier": "bronze",
  "loyalty_points": 0,
  "created_at": "2026-01-24T10:00:00Z"
}

---

Get Customer

Retrieve a single customer by ID.

GET /api/v1/customers/{customer_id}

Path Parameters

Parameter	Type	Description
customer_id	uuid	Customer ID

Response

{
  "id": "cust_abc123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "birthday": "1990-05-15",
  "loyalty_tier": "gold",
  "loyalty_points": 1250,
  "total_orders": 45,
  "total_spent": 1234.56,
  "preferences": {
    "dietary_restrictions": ["vegetarian"],
    "favorite_items": ["item_123", "item_456"]
  },
  "addresses": [
    {
      "id": "addr_123",
      "type": "home",
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001"
    }
  ],
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2026-01-20T15:30:00Z"
}

---

Update Customer

Update customer profile information.

PUT /api/v1/customers/{customer_id}

Request Body

{
  "first_name": "John",
  "last_name": "Smith",
  "phone": "+1987654321",
  "preferences": {
    "dietary_restrictions": ["vegetarian", "gluten-free"]
  }
}

---

Loyalty Endpoints

Get Loyalty Status

Retrieve customer's loyalty program status.

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

Response

{
  "customer_id": "cust_abc123",
  "tier": "gold",
  "points_balance": 1250,
  "points_earned_ytd": 3500,
  "points_redeemed_ytd": 2250,
  "tier_progress": {
    "current_tier": "gold",
    "next_tier": "platinum",
    "points_to_next_tier": 750,
    "qualifying_period_end": "2026-12-31"
  },
  "benefits": [
    "10% off all orders",
    "Free birthday dessert",
    "Priority reservations"
  ]
}

---

Adjust Loyalty Points

Add or subtract loyalty points (manager action).

POST /api/v1/customers/{customer_id}/loyalty/points

Request Body

{
  "adjustment": 100,
  "reason": "Customer service gesture",
  "order_id": "ord_optional"
}

note

Use negative values to deduct points.

---

Redeem Loyalty Points

Redeem points for rewards.

POST /api/v1/customers/{customer_id}/loyalty/redeem

Request Body

{
  "points": 500,
  "reward_type": "discount",
  "order_id": "ord_abc123"
}

Response

{
  "redemption_id": "red_xyz789",
  "points_redeemed": 500,
  "reward_value": 5.00,
  "new_balance": 750
}

---

List Loyalty Transactions

View history of loyalty point transactions.

GET /api/v1/customers/{customer_id}/loyalty/transactions

Query Parameters

Parameter	Type	Description
start_date	date	Filter from date
end_date	date	Filter to date
type	string	earn, redeem, adjust, expire
limit	integer	Results per page

Response

{
  "data": [
    {
      "id": "txn_001",
      "type": "earn",
      "points": 50,
      "description": "Order #A-0042",
      "order_id": "ord_abc123",
      "created_at": "2026-01-20T12:00:00Z"
    },
    {
      "id": "txn_002",
      "type": "redeem",
      "points": -200,
      "description": "Redeemed for $2.00 discount",
      "order_id": "ord_def456",
      "created_at": "2026-01-22T15:30:00Z"
    }
  ]
}

---

Customer Orders

List Customer Orders

View order history for a customer (customer-facing).

GET /api/v1/customers/orders

Query Parameters

Parameter	Type	Description
status	string	Filter by order status
location_id	uuid	Filter by location
limit	integer	Results per page

---

Create Customer Order

Place a new order (customer-facing online ordering).

POST /api/v1/customers/orders

Request Body

{
  "location_id": "loc_abc123",
  "order_type": "PICKUP",
  "items": [
    {
      "menu_item_id": "item_123",
      "quantity": 2,
      "modifiers": [
        {"modifier_id": "mod_001", "quantity": 1}
      ],
      "special_instructions": "No onions"
    }
  ],
  "scheduled_time": "2026-01-24T18:30:00Z",
  "tip_amount": 5.00,
  "payment_method_id": "pm_xyz789"
}

---

Calculate Order Total

Preview order total before placing.

POST /api/v1/customers/orders/calculate-total

Request Body

{
  "location_id": "loc_abc123",
  "items": [
    {"menu_item_id": "item_123", "quantity": 2}
  ],
  "promo_code": "SAVE10"
}

Response

{
  "subtotal": 24.99,
  "tax": 2.25,
  "discount": 2.50,
  "tip": 0,
  "total": 24.74,
  "promo_applied": {
    "code": "SAVE10",
    "discount": 2.50,
    "description": "10% off your order"
  }
}

---

Error Responses

Status	Code	Description
400	invalid_email	Email format is invalid
400	invalid_loyalty_tier	Tier must be bronze/silver/gold/platinum
404	customer_not_found	Customer ID does not exist
409	email_exists	Email already registered
422	insufficient_points	Not enough points for redemption

---

Related Documentation

• Loyalty API - Customer loyalty program
• Orders API - Order management
• Payments API - Payment processing