WhereFour Mock Implementation Guide

Purpose: Build a comprehensive Mockoon mock of the WhereFour API for Cleveland Kitchen POC testing and Dagster pipeline simulation.

Data Source: WhereFour OpenAPI spec v1.0.20 (received March 5, 2026)

Core Endpoints to Mock

1. Customer Management

`GET /customers`

Purpose: List all customers
Response: Paginated array of customer objects
CK Test Data:

Giant Eagle (distributor, pricing tier: $20/unit for Kimchi Classic)
Heinen’s (retail, legacy .xls order format)
Rainforest Alliance (wholesaler)
Four Seasons (produce distributor)
Sysco (large distributor)

Schema Fields (from OpenAPI):

{
  "id": "cust_001",
  "name": "Giant Eagle",
  "kind": "distributor|retail|wholesaler",
  "status": "active|inactive",
  "locations": [
    {
      "id": "loc_001",
      "name": "Cleveland Distribution Center",
      "address": "...",
      "city": "Cleveland",
      "state": "OH",
      "zip": "44114",
      "type": "shipping|billing|warehouse"
    }
  ],
  "pricing_tier": "distributor_tier_1",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2026-03-05T12:00:00Z"
}

`GET /customers/search?query=Giant%20Eagle`

Purpose: Search customers by name or partial match
Response: Array of matching customers with confidence scores

`GET /customers/{customer_id}`

Purpose: Get single customer with all locations and pricing
Critical for: Address validation, pricing tier lookup

`GET /customers/{customer_id}/orders`

Purpose: Order history for a customer
Used for: “Same as last time” order detection (Phase 3+)

2. Inventory Management

`GET /inventory`

Purpose: List all inventory items (products)
Response: Paginated array of inventory objects
CK Test Data: 10+ products with UPC variations

Kimchi Classic (12-digit: 850004476017, 14-digit: 00850004476017)
Kimchi Spicy (12-digit: 850004476024, 14-digit: 00850004476024)
Kraut Caraway (12-digit: 850004476031, 14-digit: 00850004476031)
Plus: Pickles, Salsas (various flavors)
Allowance items: Discount line items for customer pricing tiers

Schema Fields:

{
  "id": "inv_001",
  "sku": "KIM-CLASSIC-16OZ",
  "name": "Kimchi - Classic 16 oz",
  "upc_12": "850004476017",
  "upc_14": "00850004476017",
  "category": "Products|Allowances|Parts",
  "unit_price": 21.5,
  "quantity_on_hand": 450,
  "reorder_level": 100,
  "is_allowance": false,
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2026-03-05T12:00:00Z"
}

`GET /inventory/search?query=kimchi`

Purpose: Search products by SKU, name, or UPC
Critical for: SKU/product lookup during extraction Must support: Both 12-digit and 14-digit UPC variations

`GET /inventory/{inventory_id}/stocks`

Purpose: Stock levels by location
Note: Cleveland Kitchen uses non-blocking validation (do NOT use for validation)

3. Order Management

`POST /orders`

Purpose: Create new order
Used by: Ordermatic’s Phase 2 integration
Request Body:

{
  "customer_id": "cust_001",
  "requested_delivery_date": "2026-03-19T00:00:00Z",
  "line_items": [
    {
      "sku": "KIM-CLASSIC-16OZ",
      "quantity": 20,
      "unit_price": 20.0
    },
    {
      "sku": "DISCOUNT-GE-KIMCHI-1.50",
      "quantity": 20,
      "unit_price": -1.5
    }
  ]
}

Response:

{
  "id": "ord_12345",
  "customer_id": "cust_001",
  "order_date": "2026-03-05T17:18:00Z",
  "requested_delivery_date": "2026-03-19T00:00:00Z",
  "line_items": [...],
  "subtotal": 400.00,
  "discounts": 30.00,
  "total": 370.00,
  "status": "pending",
  "created_at": "2026-03-05T17:18:00Z",
  "updated_at": "2026-03-05T17:18:00Z"
}

`GET /orders`

Purpose: List all orders (paginated)
Used for: Validation testing

`GET /orders/{order_id}`

Purpose: Retrieve single order with full details

`GET /orders/search?customer_id=cust_001`

Purpose: Search orders by customer, date range, status
Used for: “Same as last time” lookup

4. Pricing & Allowances

`GET /customers/{customer_id}/pricing-tiers` (Custom Endpoint)

Purpose: Get all pricing agreements for a customer
Critical for: Detecting new customer/SKU combinations, applying discounts

Response (inferred from business logic):

{
  "customer_id": "cust_001",
  "name": "Giant Eagle",
  "tiers": [
    {
      "sku": "KIM-CLASSIC-16OZ",
      "list_price": 21.5,
      "customer_price": 20.0,
      "effective_date": "2026-01-01T00:00:00Z",
      "discount_amount": 1.5,
      "discount_allowance_sku": "DISCOUNT-GE-KIMCHI-1.50"
    },
    {
      "sku": "KIM-SPICY-16OZ",
      "list_price": 22.0,
      "customer_price": 21.0,
      "effective_date": "2026-01-01T00:00:00Z",
      "discount_amount": 1.0,
      "discount_allowance_sku": "DISCOUNT-GE-KIMCHI-SPICY-1.00"
    }
  ]
}

Mock Data Setup

Cleveland Kitchen Test Customers

Customer	Type	Key Attributes	Order Format
Giant Eagle	Distributor	Pricing: $20/unit (list $21.50), 15 lines/order	`.xlsx`
Heinen’s	Retail	Legacy system, multiple SKUs	`.xls` binary
Rainforest Alliance	Wholesaler	Standard pricing	PDF emails
Four Seasons Produce	Wholesaler	Clean format	PDF emails
Sysco	Distributor	Large volume	PDF/email

Inventory Master Data

Create 15-20 products across categories:

Kimchi: Classic, Spicy (2 flavors × 2 UPC formats = 4 SKUs)
Krauts: Caraway, Curry (2 flavors × 2 UPC formats = 4 SKUs)
Pickles: Dill, Bread & Butter (2 flavors × 2 UPC formats = 4 SKUs)
Salsas: Red, Green (2 flavors × 2 UPC formats = 4 SKUs)
Allowances: Discount line items for each customer tier (8 SKUs)

UPC Format Examples:

12-digit: 850004476017 (common)
14-digit: 00850004476017 (leading zeros)
Variations: some customers drop leading/trailing zeros

Pricing Tiers

Create customer-specific pricing for:

Giant Eagle: $20/unit Kimchi Classic (vs $21.50 list)
Heinen’s: $19.50/unit Kraut Caraway (vs $19.99 list)
Rainforest: List pricing (no discount)
Sysco: Volume-based discounts (e.g., 10+ units = $20.75)

Mockoon Configuration

Base URL

Development: http://localhost:3010/api/v1
Match OpenAPI servers: https://my.wherefour.com/api/v1 (production), https://sandbox.wherefour.com/api/v1 (sandbox)

CORS & Headers

{
  "cors": true,
  "corsOptions": {
    "origin": "*",
    "credentials": true,
    "maxAge": 86400
  }
}

Response Headers (for paginated endpoints)

Content-Type: application/json
Total: Total count of results
Per-Page: Number of results per page
Link: URLs for next/previous pages

Dagster Pipeline Integration

Crawl Phase

Dagster pipeline should:

GET /inventory → Extract all products
GET /inventory/search → Test fuzzy matching
GET /customers → Extract all customers + locations
GET /customers/{id} → Extract customer details

Sync Phase

Sync inventory to Ordermatic product cache
Sync customer locations to address validator
Cache pricing tiers locally (for offline validation)

Validation Testing Phase

Create test order: POST /orders with sample CK data
Verify response: order created with correct ID, status, totals
Look up order: GET /orders/{id} → verify retrieval
Test edge cases:
- New customer/SKU combo (should fail pricing validation in Phase 2)
- Missing address (should flag in Ordermatic)
- Unknown UPC variation (should be normalized + matched)

Success Criteria

Mock Completeness

✅ All 8 core endpoints mocked with realistic data
✅ Paginated responses with correct headers
✅ 15+ inventory items with UPC variations
✅ 3-5 customers with multiple locations
✅ Pricing tier lookup working
✅ Order creation returns proper response

Dagster Pipeline

✅ Pipeline runs against mock without errors
✅ Inventory sync completes
✅ Customer lookup works
✅ Pricing tier cache populates

Ordermatic Integration (Phase 2)

✅ Extraction validates against mock WhereFour
✅ Order submission creates records in mock
✅ Address validation passes/fails correctly
✅ Pricing validation detects new customer/SKU combos

Future Enhancements

Phase 3+: Advanced Endpoints

/orders/search with date range filters
/customers/{id}/orders for order history
/reports/activities for audit trails
Webhook support for status updates

Phase 4: Theme Skill Integration

Custom pricing rules per customer
Automated quote generation
Order status notifications

Implementation Checklist

Mockoon collection created with all 8 endpoints
Test data seeded (customers, products, pricing)
CORS configured for localhost:3010
Docker Compose includes Mockoon service
Dagster pipeline integration tested
Ordermatic extraction validated against mock
Phase 1 PoC testing completed
Ready for Phase 2 (WhereFour real sandbox testing)