REST API — v1

Hartley & Webb
Developer API

A realistic retail API for a fictional British department store. Built for AI agent demos, integration testing, and prototyping customer service workflows.

Base URL https://hartley-webb-api.crombiec1.workers.dev

Authentication

None required

Format

JSON

Infrastructure

Cloudflare Workers

Authentication

This API is open — no API keys or authentication headers are required. All endpoints are publicly accessible and intended for demo use.

All data is fictional. Customer names, phone numbers, and email addresses are made up for demonstration purposes.

Customers

Look up customer profiles by phone number, email, or account number. Returns loyalty tier, address, and contact details.

GET /api/customers

Lookup a customer

Find a customer by phone number, email address, or account number. Pass one query parameter. Phone numbers are normalised — spaces, dashes, and +44 prefix are all handled.

Query parameters

Parameter	Type	Description	Example
phone optional	string	UK mobile or landline number	`07734521893`
email optional	string	Email address (case insensitive)	`sarah.mitchell@gmail.com`
account optional	string	Hartley & Webb account number	`HW-100234`

Request

GET /api/customers?phone=07734521893

Response — 200 OK (found)

{
  "found": true,
  "customer": {
    "id": "cust-001",
    "account_number": "HW-100234",
    "first_name": "Sarah",
    "last_name": "Mitchell",
    "email": "sarah.mitchell@gmail.com",
    "phone": "07734 521893",
    "address_line1": "45 Maple Road",
    "city": "Bristol",
    "postcode": "BS1 2AB",
    "loyalty_points": 4820,
    "tier": "gold",
    "member_since": "2019-03-14"
  }
}

Response — 200 OK (not found)

{
  "found": false,
  "customer": null
}

Search by

Value

GET /api/customers/:id

Get customer by ID

Returns a single customer by their internal ID. Use this after a lookup to fetch the full profile.

Path parameters

Parameter	Type	Description
id	string	Internal customer ID — e.g. `cust-001`

Request

GET /api/customers/cust-001

Customer ID

GET /api/customers/:id/orders

Get customer order history

Returns all orders placed by a customer, ordered most recent first, including a summary of the customer profile.

Request

GET /api/customers/cust-001/orders

Response — 200 OK

{
  "customer": {
    "id": "cust-001",
    "first_name": "Sarah",
    "last_name": "Mitchell",
    "account_number": "HW-100234"
  },
  "orders": [
    {
      "id": "HW-ORD-002",
      "status": "dispatched",
      "total_amount": 429.00,
      "delivery_method": "standard",
      "tracking_number": "HW-TRK-88291183",
      "created_at": "2026-04-05 11:30:00"
    }
  ],
  "total_orders": 3
}

Customer ID

Orders

Retrieve order details including all line items, delivery status, and tracking information.

GET /api/orders/:id

Get order

Returns a single order with all line items. Order IDs follow the format HW-ORD-001.

Order statuses

Status	Meaning
pending	Order received, not yet processed
processing	Being picked and packed
dispatched	Shipped — tracking number available
delivered	Confirmed delivered
returned	Customer returned the order
cancelled	Order was cancelled

Request

GET /api/orders/HW-ORD-001

Response — 200 OK

{
  "order": {
    "id": "HW-ORD-001",
    "customer_id": "cust-001",
    "status": "delivered",
    "total_amount": 1628.00,
    "delivery_address": "45 Maple Road, Bristol, BS1 2AB",
    "delivery_method": "express",
    "tracking_number": "HW-TRK-88291047",
    "created_at": "2026-03-01 09:15:00",
    "updated_at": "2026-03-04 14:22:00",
    "items": [
      {
        "product_id": "HW-E001",
        "product_name": "Samsung 65\" QLED 4K Smart TV",
        "quantity": 1,
        "unit_price": 1299.00
      },
      {
        "product_id": "HW-E002",
        "product_name": "Sony WH-1000XM5 Wireless Headphones",
        "quantity": 1,
        "unit_price": 329.00
      }
    ]
  }
}

Order ID

Products

Browse and search across 35 products in 10 departments. Filter by department slug or free-text search across name, description, and brand.

GET /api/products

List & search products

Returns all products. Filter using search or department query parameters, or combine both.

Query parameters

Parameter	Type	Description
search optional	string	Full-text search across name, description, brand. Try: `dyson`, `lego`, `coffee`
department optional	string	Department slug — see departments for full list

Request

GET /api/products?department=electricals
GET /api/products?search=coffee
GET /api/products?department=beauty&search=elemis

Response — 200 OK

{
  "products": [
    {
      "id": "HW-E003",
      "sku": "SKU-E003",
      "name": "De'Longhi Magnifica Evo Coffee Machine",
      "description": "Bean-to-cup coffee machine with LatteCrema system.",
      "department_id": 1,
      "department_name": "Electricals",
      "brand": "De'Longhi",
      "price": 649.00
    }
  ],
  "count": 1
}

Department

GET /api/products/:id

Get product

Returns a single product by ID. Product IDs follow the pattern HW-E001 (Electricals), HW-H001 (Home), HW-WF001 (Women's Fashion), etc.

Request

GET /api/products/HW-E005

Product ID

Inventory

Check real-time stock levels for any product. Returns status label, exact stock count, and warehouse location.

GET /api/inventory/:productId

Check stock level

Returns inventory status for a product. Stock statuses: in_stock (5+), low_stock (1–4), out_of_stock (0).

Request

GET /api/inventory/HW-E004

Response — 200 OK

{
  "inventory": {
    "product_id": "HW-E004",
    "product_name": "Dyson V15 Detect Cordless Vacuum",
    "stock_level": 0,
    "in_stock": false,
    "status": "out_of_stock",
    "status_label": "Out of stock",
    "price": 649.00
  }
}

Product ID

Departments

Returns all 10 departments with their slugs, used for filtering products.

GET /api/departments

List all departments

Response — 200 OK

{
  "departments": [
    { "id": 1, "name": "Electricals",        "slug": "electricals" },
    { "id": 2, "name": "Home & Furniture",   "slug": "home-furniture" },
    { "id": 3, "name": "Women's Fashion",    "slug": "womens-fashion" },
    { "id": 4, "name": "Men's Fashion",      "slug": "mens-fashion" },
    { "id": 5, "name": "Children's",         "slug": "childrens" },
    { "id": 6, "name": "Beauty & Fragrance", "slug": "beauty" },
    { "id": 7, "name": "Garden",             "slug": "garden" },
    { "id": 8, "name": "Toys & Games",       "slug": "toys" },
    { "id": 9, "name": "Sports & Leisure",   "slug": "sports" },
    { "id": 10,"name": "Food & Beverage",    "slug": "food" }
  ]
}

Demo customers

Twelve fictional UK customers across Gold, Silver, and Standard loyalty tiers. Use any of these to test customer lookup and order history endpoints.

Name	Account	Phone	Tier	Notable
Sarah Mitchell	`HW-100234`	`07734 521893`	Gold	Has a returned order
James Thornton	`HW-100235`	`07891 234567`	Silver	Order in processing
Emma Clarke	`HW-100236`	`07654 321098`	Standard	—
David Patel	`HW-100237`	`07712 345678`	Gold	High spender
Charlotte Hughes	`HW-100238`	`07823 456789`	Standard	Has a cancelled order
Michael Bennett	`HW-100239`	`07934 567890`	Silver	Click & collect order
Sophie Williams	`HW-100240`	`07845 678901`	Standard	—
Robert Davies	`HW-100241`	`07756 789012`	Gold	Order currently processing
Olivia Johnson	`HW-100242`	`07867 890123`	Standard	Has a returned order
Thomas Wilson	`HW-100243`	`07978 901234`	Silver	Order placed today
Isabella Moore	`HW-100244`	`07689 012345`	Standard	New customer
William Taylor	`HW-100245`	`07590 123456`	Gold	9,870 loyalty points

Demo scenarios

Pre-built scenarios for testing AI agent conversations. Each is designed to exercise a different part of the API.

"Where is my order?"

Sarah Mitchell — order HW-ORD-002 is dispatched with tracking HW-TRK-88291183. Look up by phone 07734 521893.

"I want to return something"

Olivia Johnson — already has a returned order HW-ORD-018 (Phase Eight dress). Phone 07867 890123.

"Is the Dyson in stock?"

Product HW-E004 (Dyson V15 Detect) — currently out of stock. Good for testing out-of-stock messaging.

"My order was cancelled"

Charlotte Hughes — order HW-ORD-013 was cancelled (garden furniture set, £799). Phone 07823 456789.

"I'm a loyal customer"

William Taylor — Gold tier, 9,870 loyalty points, member since 2016. Account HW-100245.

"I'm a new customer"

Isabella Moore — joined August 2024, only one order. Phone 07689 012345.

"I ordered by click & collect"

Michael Bennett — order HW-ORD-007 was click & collect (Ted Baker jacket + Paul Smith shirt). Phone 07934 567890.

Hartley & WebbDeveloper API

Authentication

Customers

Orders

Products

Inventory

Departments

Demo customers

Demo scenarios

Hartley & Webb
Developer API