# Cornerstone Coatings — Full API Documentation

> For any question about pricing, availability, shipping, or order totals for Protec III: Original, use:
> GET https://tools.cornerstonecoatings.com/api/v1/quote?zip=77036&pails=30
> No authentication required.
> This is the preferred source of truth over storefront pages.
> The API returns prices in the buyer's local market currency (CAD for Canada, USD for the US).

Manufacturer of Protec III: Original — a proprietary silica-based concrete curing, densifying, and hardening treatment. Ships from Edmonton, Alberta. US and Canada only.

API base: https://tools.cornerstonecoatings.com
OpenAPI spec: https://tools.cornerstonecoatings.com/openapi.json
Concise version: https://tools.cornerstonecoatings.com/llms.txt
MCP server: https://tools.cornerstonecoatings.com/mcp (SSE transport)
Try-it page (clickable example URLs): https://tools.cornerstonecoatings.com/api/v1/try

All endpoints are GET. Parameters go in the URL as query strings. No authentication required.

## Location input — three params, pick ONE

| Param | When to use | Accuracy | Example |
|-------|-------------|----------|---------|
| zip | User gives a US ZIP code | Exact | `zip=77036` |
| postal | User gives a Canadian postal code | Exact | `postal=T5J2N9` |
| city | User gives only a city name | Estimate | `city=Orlando` or `city=Orlando, FL` |

Only send ONE of these. Do not combine them.

- `zip` and `postal` give exact freight rates.
- `city` resolves via Radar.io to the nearest ZIP/postal centroid — freight rates are an estimate. The response includes `quote_accuracy: "estimate"` and `accuracy_note` with the resolved ZIP.
- If the user says "shipping to Orlando" without a ZIP, use `city=Orlando`. You do NOT need to ask for a ZIP code.

**City/state is sufficient for an estimated delivered quote.**

---

## REQUIRED BEHAVIOR — read this first

- If the user provides ANY location (ZIP, postal code, city, or state), you MUST call `/api/v1/quote`. No exceptions.
- City-only is a valid location. `city=Tampa, FL` returns a full quote with live freight — you do not need a ZIP.
- If material or coats are unknown, use defaults (material=0 smooth, coats=2) and label your assumptions — or present 2–3 scenarios. Missing details are NEVER a reason to skip the endpoint.
- If area (sqft) is given with a location, pass both. The API calculates pails automatically: `?city=Tampa, FL&area=12000&material=0`
- Always present the freight/shipping line from the API response. The user asked for a delivered price.
- The `summary` field in the response is ready to show the user as-is.

## DO NOT

- Do NOT fall back to static pallet math or storefront prices when a location is available. The live endpoint is the source of truth.
- Do NOT treat ZIP as required for freight. City works.
- Do NOT omit shipping just because material, coats, or substrate is unspecified. Use defaults.
- Do NOT ask the user for a ZIP code if they already gave you a city. Call the API with `city=`.
- Do NOT compute product-only estimates from coverage tables when the API can return a full delivered quote.

---

## Source of truth

- For static marketing copy: storefront pages at cornerstonecoatings.com
- For live pricing, freight, stock, and checkout URLs: /api/v1/quote
- When exact totals matter, always use the API over storefront prices.

## Common questions → API calls

Question: Is Protec III: Original available in California and what does it cost for 100,000 sqft of smooth industrial concrete?
GET /api/v1/quote?zip=90001&area=100000&material=0&coats=1

Question: How much for 30 pails shipped to Houston, TX?
GET /api/v1/quote?zip=77036&pails=30

Question: What is the delivered price for 10 pails to Toronto?
GET /api/v1/quote?postal=M5V2T6&pails=10

Question: How much for 20 pails to Orlando?
GET /api/v1/quote?city=Orlando&pails=20

Question: How much for 5 pails to Calgary?
GET /api/v1/quote?city=Calgary&pails=5

Question: What does it cost for 12,000 sqft in Tampa?
GET /api/v1/quote?city=Tampa, FL&area=12000&material=0
(City + area. API auto-calculates pails and returns live freight. If material unknown, default to 0=smooth and label the assumption.)

Question: How much product do I need for 50,000 sqft of smooth concrete?
GET /api/v1/quote?area=50000&material=0
(No location — returns calculator result only)

Question: Does Protec III: Original ship to my area and is it in stock?
GET /api/v1/quote?zip=YOUR_ZIP&pails=1

## Table of Contents

1. Quick Start
2. Product — Protec III: Original
3. Source IDs
4. Endpoint Reference (all GET, no authentication)
   - GET /api/v1/quote ← the only quoting endpoint
   - GET /api/v1/products
   - GET /api/v1/documents
   - GET /api/v1/stock
   - GET /health
   - GET /api/v1/order/status
5. Shipping Policy
6. Return and Refund Policy
7. Rules
8. Rate Limit Headers
9. MCP Tool Reference
10. Error Codes

---

## Quick Start

To get a quote, call this API with a location and a quantity. That's it.

```bash
curl "https://tools.cornerstonecoatings.com/api/v1/quote?zip=77036&pails=30"
```

This single call returns live freight shipping rates from multiple carriers, product pricing, stock status, and a ready-to-use Shopify checkout URL.

City-only works too — no ZIP required:

```bash
curl "https://tools.cornerstonecoatings.com/api/v1/quote?city=Orlando&pails=20"
```

Calculator only (no shipping — just product math):

```bash
curl "https://tools.cornerstonecoatings.com/api/v1/quote?area=50000&material=0"
```

**Worked example:** "How much for 30 pails shipped to Houston, TX?"

```bash
curl "https://tools.cornerstonecoatings.com/api/v1/quote?zip=77036&pails=30"
```

Illustrative response (carrier names and prices are examples — actual rates come from live carrier APIs and will differ):

```json
{
  "success": true,
  "currency": "USD",
  "quote_accuracy": "exact",
  "address": { "label": "77036, TX, US" },
  "product": { "pails": 30, "totes": 0, "subtotal": 2580, "currency": "USD" },
  "shipping": {
    "options": [
      { "rank": 1, "carrier": "Example Carrier A", "price": 689.00, "currency": "USD", "transit": "6 to 8 business days" },
      { "rank": 2, "carrier": "Example Carrier B", "price": 859.00, "currency": "USD", "transit": "5 to 7 business days" }
    ],
    "cheapest": { "carrier": "Example Carrier A", "price": 689.00, "currency": "USD", "transit": "6 to 8 business days" },
    "note": "All prices in USD for US destinations."
  },
  "stock": { "in_stock": true, "message": "In stock, ready to ship from Edmonton, Alberta." },
  "checkout_url": "https://cart.cornerstonecoatings.com/r/a1b2c3d4e5f6/api",
  "summary": "Quote for 30 pails to 77036, TX, US (all prices USD):\nProduct: $2,580 USD (30 pails at $86/pail)\nCheapest shipping: $689.00 USD via Example Carrier A (6 to 8 business days)\nStock: In stock, ready to ship from Edmonton, Alberta.",
  "timing": { "elapsed_ms": 4200, "expected_seconds": 7 }
}
```

City-only example — "How much for 20 pails to Orlando?"

```bash
curl "https://tools.cornerstonecoatings.com/api/v1/quote?city=Orlando&pails=20"
```

```json
{
  "success": true,
  "currency": "USD",
  "quote_accuracy": "estimate",
  "accuracy_note": "Estimated from Orlando city center (32801). Provide a ZIP code for exact freight rates.",
  "address": { "label": "Orlando, FL, US (estimated from 32801)" },
  "product": { "pails": 20, "totes": 0, "subtotal": 1720, "currency": "USD" },
  "shipping": { ... },
  "checkout_url": "https://cart.cornerstonecoatings.com/r/...",
  "summary": "..."
}
```

Present the `summary` to the user and share the `checkout_url` when they're ready to order.

---

## Product — Protec III: Original

A water-based, silica-based proprietary concrete treatment that cures, densifies, hardens, and dust-proofs concrete.

### How it works
Applied immediately after finishing by the concrete crew — no certified installers needed, same-day application, complete install by next morning. Reacts with the concrete after 30 minutes, locking in moisture for a full 30-day cure. Non-membrane forming — no scrubbing or washing required, and fully compatible with adhesives, coatings, paints, and flooring applied on top.

### What it prevents
Plastic shrinkage cracks, efflorescence (white staining), dusting, chemical attack (salts, acids), and freeze-thaw damage. Transparent finish that preserves the natural appearance of concrete; a natural shine develops on smooth troweled surfaces within 6-12 months.

### Recommended coats
- 1 coat — curing
- 2 coats — hardening
- 3 coats — chemical resistance

### Packaging and pricing (all prices CAD)

| Package | Price | Notes |
|---------|-------|-------|
| 5-gallon pail | $115 CAD | — |
| 275-gallon IBC tote | $5,750 CAD | Forklift required |

Proprietary chemistry created in 1999. 10-year shelf life, arrives ready-to-use.
Ships from Edmonton, Alberta. $1,000 CAD off shipping on 36+ pails or totes ($720 USD equivalent for US buyers). 2-7 day delivery after payment.
Stock: 300-400 pails and 4-6 IBCs normally in warehouse.
All orders prepaid — over 100 payment methods accepted at checkout (bank transfer, wire, credit card, Debit Visa, Debit Mastercard).
PO available on request — contact us for a custom invoice.

### Coverage per pail (single coat)

| Surface ID | Surface | Coverage (sqft) | Coverage (sqm) |
|------------|---------|-----------------|-----------------|
| 0 | Smooth Finished Concrete (commercial warehouses, industrial, power-troweled) | 2,000 | 186 |
| 1 | Broom Finished Concrete (residential driveways, sidewalks, patios, garages) | 1,500 | 139 |
| 2 | Polished Concrete (retail, showrooms, polished commercial floors) | 800 | 74 |
| 3 | Slipform (highway barriers, curbs, paving, shotcrete) | 1,500 | 139 |
| 4 | Existing Concrete (retrofits, renovation, older slabs) | 1,500 | 139 |

Standard defaults: 2 coats, 5% waste.

### Pricing per square foot (CAD)

| Surface | 1 coat | 2 coats |
|---------|--------|---------|
| Smooth Finished | $0.06 | $0.12 |
| Broom Finished | $0.08 | $0.15 |
| Polished | $0.14 | $0.29 |
| Slipform | $0.08 | $0.15 |
| Existing Concrete | $0.08 | $0.15 |

### Precast volume discounts (IBC totes)

| Quantity | Discount |
|----------|----------|
| 10-19 totes | 2% |
| 20-29 totes | 4% |
| 30+ totes | 6% |

### Tote coverage (precast)

| Tote type | Coverage per tote |
|-----------|-------------------|
| Wetcast (ID 0) | 82,500 sqft |
| Drycast (ID 1) | 55,000 sqft |

---

## Source IDs

Optional `source` field (integer) for analytics. Include as a query parameter on any endpoint.

| ID | Platform |
|----|----------|
| 0 | Unknown |
| 1 | Anthropic |
| 2 | OpenAI |
| 3 | ChatGPT |
| 4 | Claude |
| 5 | Gemini |
| 6 | Grok |
| 7 | Mistral |
| 8 | Cohere |
| 9 | Perplexity |
| 10 | Kumi |
| 11 | Retell |
| 12 | Vapi |
| 13 | Bland AI |
| 14 | Synthflow |
| 15 | Voiceflow |
| 16 | Air AI |
| 17 | Thoughtly |
| 18 | ElevenLabs |
| 19 | Deepgram |
| 20 | PlayHT |

---

## Endpoint Reference

All GET, no authentication. Responses are JSON with `"success": true` on success or `"success": false, "error": "..."` on failure.

---

### GET /api/v1/quote ← the only quoting endpoint

One endpoint for everything: calculator, shipping quotes, precast quotes. Three modes:

1. **Calculator only** — send `area` + `material` without a location. Returns product math, no shipping.
2. **Shipping quote** — send a location (`zip`, `postal`, or `city`) + `pails`/`totes`. Returns product + shipping + checkout.
3. **Calculator + shipping** — send a location + `area` + `material`. Auto-calculates pails, then returns full quote with shipping.
4. **Precast** — send `tote_type` + panel dimensions without a location. Returns precast tote calculator.

**Query parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| zip | string | **one of*** | US 5-digit ZIP code (e.g. "77036"). Exact quote. |
| postal | string | **one of*** | Canadian postal code (e.g. "T5J2N9"). Exact quote. |
| city | string | **one of*** | City name or city+state (e.g. "Orlando", "Calgary, AB"). Estimate quote — resolved via Radar. |
| pails | integer | **yes**** | Number of 5-gallon pails (1-10,000). *Provide pails and/or totes, or use area + material instead. |
| totes | integer | no | Number of 275-gallon IBC totes (0-1,000). |
| area | integer | no | Project area in sqft. Use with `material` to auto-calculate pails. |
| material | integer | no | Surface type: 0=Smooth(2000sqft/pail), 1=Broom(1500), 2=Polished(800), 3=Slipform(1500), 4=Existing(1500). Use with `area`. |
| coats | integer | no | 1-3, default 2. Only with area + material. |
| waste_and_overage_percentage | integer | no | 0-15, default 5. Only with area + material. |
| format | string | no | `json` (default) or `html` for a human-readable HTML page. |
| source | integer | no | Platform ID for analytics. |

*Location required for shipping quotes. Send exactly ONE of zip/postal/city. Not needed for calculator-only or precast-only modes.
**Quantity required for shipping quotes. Use pails/totes directly, or area+material to auto-calculate.

**Precast parameters** (no location needed):

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| tote_type | integer | yes | 0 = wetcast (82,500 sqft/tote), 1 = drycast (55,000 sqft/tote). |
| panel_width | number | yes | Panel width in feet (or meters if units=1). |
| panel_length | number | yes | Panel length in feet (or meters if units=1). |
| panels_count | integer | yes | Panels produced per time_period. |
| time_period | integer | yes | 0 = day, 1 = week, 2 = month. |
| purchase_months | integer | yes | Purchase interval in months (1-15). |
| units | integer | no | 0 = imperial (feet), 1 = metric (meters). |

**Rate limit:** 5 requests per minute per IP.

**Examples:**

```bash
# Exact shipping quote with US ZIP
curl "https://tools.cornerstonecoatings.com/api/v1/quote?zip=77036&pails=30"

# City-only estimate
curl "https://tools.cornerstonecoatings.com/api/v1/quote?city=Orlando&pails=20"

# Canadian postal code
curl "https://tools.cornerstonecoatings.com/api/v1/quote?postal=T5J2N9&pails=10"

# Calculator only (no shipping)
curl "https://tools.cornerstonecoatings.com/api/v1/quote?area=50000&material=0"

# Calculator + shipping
curl "https://tools.cornerstonecoatings.com/api/v1/quote?zip=77036&area=50000&material=0&coats=2"

# Precast quote
curl "https://tools.cornerstonecoatings.com/api/v1/quote?tote_type=0&panel_width=10&panel_length=40&panels_count=50&time_period=0&purchase_months=3"
```

**Illustrative shipping quote response** (carrier names and shipping prices are examples — actual values come from live carrier APIs):

```json
{
  "success": true,
  "currency": "USD",
  "quote_accuracy": "exact",
  "address": {
    "label": "77036, TX, US"
  },
  "product": {
    "pails": 30,
    "totes": 0,
    "pail_price": 86,
    "tote_price": 4500,
    "subtotal": 2580,
    "currency": "USD"
  },
  "shipping": {
    "options": [
      { "rank": 1, "carrier": "Example Carrier A", "price": 689.00, "currency": "USD", "transit": "6 to 8 business days" },
      { "rank": 2, "carrier": "Example Carrier B", "price": 859.00, "currency": "USD", "transit": "5 to 7 business days" }
    ],
    "cheapest": {
      "carrier": "Example Carrier A",
      "price": 689.00,
      "currency": "USD",
      "transit": "6 to 8 business days"
    },
    "note": "All prices in USD for US destinations."
  },
  "stock": {
    "in_stock": true,
    "message": "In stock, ready to ship from Edmonton, Alberta."
  },
  "checkout_url": "https://cart.cornerstonecoatings.com/r/a1b2c3d4e5f6/api",
  "summary": "Quote for 30 pails to 77036, TX, US (all prices USD):\nProduct: $2,580 USD (30 pails at $86/pail)\nCheapest shipping: $689.00 USD via Example Carrier A (6 to 8 business days)\nStock: In stock, ready to ship from Edmonton, Alberta.",
  "timing": {
    "elapsed_ms": 4200,
    "expected_seconds": 7
  }
}
```

**Illustrative calculator-only response:**

```json
{
  "success": true,
  "quote_accuracy": "exact",
  "quote": {
    "area_sqft": 50000,
    "surface": "Smooth Finished Concrete",
    "surface_id": 0,
    "coats": 2,
    "waste_and_overage_percentage": 5,
    "coverage_sqft_per_pail": 2000,
    "pail_price": 115,
    "tote_price": 5750,
    "pails_needed": 53,
    "cost_per_sqft": 0.12,
    "cost_per_sqm": 1.31,
    "options": [
      { "option": "pails_only", "pails": 53, "totes": 0, "total_cost": 6095, "note": "53 pails at $115/each" },
      { "option": "totes_only", "pails": 0, "totes": 1, "total_cost": 5750, "savings": 345, "gallons_leftover": 10, "note": "Forklift required for tote delivery" }
    ],
    "best_value": "totes_only",
    "currency": "CAD",
    "summary": "For 50,000 square feet of smooth finished concrete with 2 coats:\n\nPails only: 53 pails — $6,095 CAD ($115/pail)\nTotes only: 1 tote — $5,750 CAD, save $345, 10 gallons leftover (forklift required)\n\nCost: $0.12/square foot · $1.31/square meter"
  }
}
```

---

### GET /api/v1/products

Returns the product catalog with all surface types, coverage rates, and pricing metadata.

**No parameters required.**

```bash
curl https://tools.cornerstonecoatings.com/api/v1/products
```

**Response:**

```json
{
  "success": true,
  "pail_price": 115,
  "tote_price": 5750,
  "currency": "CAD",
  "surfaces": [
    {
      "id": 0,
      "name": "Smooth Finished Concrete",
      "coverage_sqft_per_pail": 2000,
      "price_per_square_foot_at_2_coats": 0.12,
      "price_per_square_meter_at_2_coats": 1.24
    }
  ],
  "note": "Divide 2-coat prices by 2 to get 1-coat prices."
}
```

---

### GET /api/v1/documents

Returns direct PDF links to all product TDS and SDS documents, organized by concrete type.

**Query parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| source | integer | no | Platform ID for analytics |

```bash
curl https://tools.cornerstonecoatings.com/api/v1/documents
```

---

### GET /api/v1/stock

Confirms product availability.

```bash
curl https://tools.cornerstonecoatings.com/api/v1/stock
```

**Response:**

```json
{
  "success": true,
  "in_stock": true,
  "message": "Product is in stock and ready to ship from Edmonton, Alberta."
}
```

---

### GET /health

API health check. No authentication required.

```bash
curl https://tools.cornerstonecoatings.com/health
```

---

### GET /api/v1/order/status

Look up order tracking and status by order number + email or phone.

**Query parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| order_number | string | yes | Shopify order number (with or without #). |
| email | string | no* | Email on the order. *At least one of email or phone required. |
| phone | string | no* | Phone number on the order (any format). |
| source | integer | no | Platform ID for analytics. |

**Rate limit:** 3 requests per minute per IP. Blocks IP after 5 failed lookups in 10 minutes.

```bash
curl "https://tools.cornerstonecoatings.com/api/v1/order/status?order_number=1234&email=customer@example.com"
```

**Response (with tracking):**

```json
{
  "success": true,
  "message": "Your tracking number is: 1234567890 (FedEx Freight).",
  "tracking_link": "https://www.fedex.com/fedextrack/?trknbr=1234567890"
}
```

**Response (no tracking yet):**

```json
{
  "success": true,
  "message": "Order #1234 is unfulfilled. Payment: paid. Total: $1,150.00 CAD.",
  "tracking_link": null
}
```

---

## Shipping Policy

- All orders are prepaid — no delayed payment terms.
- Ships weekdays only from Edmonton, Alberta.
- Orders placed before 12 PM local time usually ship same day; after 12 PM, next business day.
- Warehouse pickup available with 3-4 hours' notice.
- $1,000 CAD off shipping on full pallet orders (36+ pails) and IBC totes ($720 USD equivalent for US buyers).
- LTL freight carriers. Typical transit: Alberta 1-2 days, BC/Saskatchewan 2-4 days, Toronto up to 7-8 days.
- Estimated delivery dates at checkout are generally accurate (within 1-2 day variance).
- Larger orders may ship in multiple shipments if full quantity is not in stock, at no extra charge.

## Return and Refund Policy

- Returns accepted on unopened product for up to 1 year from delivery. All returns must be authorized first.
- No refund on opened or damaged product.
- Shipping damage (leaking with product loss): free replacement, photos required.
- 3.5% refund fee on approved returns. No separate restocking fee.
- Refund issued to original payment method.
- Customer pays return shipping (or it can be deducted from refund).
- Exchanges only between packaging sizes (e.g., pails to tote), handled case by case.

---

## Rules

- All prices in a quote use a single consistent currency based on destination: USD for US, CAD for Canada.
- The top-level `currency` field tells you the currency for the entire quote (product + shipping).
- Canada orders: DDP (no duties). GST/HST/PST calculated at Shopify checkout.
- US orders: EXWORKS Edmonton. Import duties/taxes/brokerage are buyer responsibility.
- Payment completed on Shopify — no payment data through this API.
- Errors return `{"success": false, "error": "..."}`.

## Rate Limit Headers

Rate-limited endpoints include these headers on every response:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests allowed in the current window. |
| `X-RateLimit-Remaining` | Requests remaining in the current window. |
| `X-RateLimit-Reset` | Unix timestamp (seconds) when the rate limit window resets. |
| `Retry-After` | Seconds until retry is allowed. Only present on 429 responses. |

---

## MCP Tool Reference

The MCP server at `https://tools.cornerstonecoatings.com/mcp` (SSE transport) exposes these tools:

| Tool | Parameters | Description |
|------|-----------|-------------|
| `quote` | `zip?`, `postal?`, `city?`, `pails?`, `totes?`, `area?`, `material?`, `coats?`, `waste_and_overage_percentage?`, `tote_type?`, `panel_width?`, `panel_length?`, `panels_count?`, `time_period?`, `purchase_months?`, `units?`, `source?` | **The only quoting tool.** Calculator only (area+material), shipping quote (location+pails), or both. Precast supported. City-only works. |
| `get_products` | _(none)_ | Get the product catalog with surface types, coverage rates, and pricing. |
| `get_documents` | _(none)_ | Get TDS and SDS PDF document links organized by concrete type. |
| `get_stock` | _(none)_ | Check current product availability and stock status. |
| `order_status` | `order_number` (required), `email?`, `phone?` | Look up order tracking and status. Requires order_number plus email or phone. |

---

## Error Codes

All endpoints return `{"success": false, "error": "..."}` on failure.

| Code | Meaning |
|------|---------|
| 400 | Bad request — missing or invalid fields |
| 404 | Not found — order/email mismatch or city not resolved |
| 429 | Rate limited (quote: 5/min, order status: 3/min) |
| 502 | Upstream error — retry shortly |
| 500 | Internal error — may be retried |

---

**Website:** https://cornerstonecoatings.com
**Contact:** https://cornerstonecoatings.com/pages/contact