provenance (where it all came from) · every claim traceable

Methodology & provenance

Where every number on this site comes from, which parts match Burq’s public documentation, and which parts are invented — each invention labeled and listed.

01What this is

The Escalation Desk is a working mock-up of an internal console — the screen a Customer Success Engineer would sit in front of all day at a delivery orchestration company, a platform that owns no trucks and hands each order to one of several courier companies. It shows the work directly: a board of customer accounts, three problems worked start to finish from the raw evidence (webhook logs, dispatch logs, quote data), and the customer email each one produces. The next section defines those words.

It exists to show triage judgment on realistic evidence, not to represent any real company’s data. Everything rendered is simulated; what is real is the shape of that data — which conforms to Burq’s public API documentation — and the published integration-readiness criteria the grading is built on. This page is the audit trail for both claims.

02Glossary: what each word means

The words an operator would actually use, with the plain meaning beside each one. Every other page on this site talks like this.

Courier (provider): The company that actually drives the package. This platform owns no vehicles — it hands each order to one of several courier companies.
Dispatch: Handing an order to a courier and asking them to pick it up.
Quote: What a courier answers when asked to take a job: a price and an estimated delivery time. The cheapest quote is not always the one to take.
Zone: A ZIP code. Delivery performance and cost vary street by street, so everything is measured per ZIP.
On-time rate: Share of deliveries that arrived within 15 minutes of the time promised at dispatch.
Failure rate: Share of orders that never got delivered at all — canceled, or stuck with no courier.
Reroute rate: Share of orders that had to be taken back from one courier mid-job and given to another. Every reroute costs time and usually money.
Cost per delivery: Average all-in cost of one delivery: what the courier charges plus the platform fee.
Webhook: The automatic message sent to a customer’s own software every time a delivery changes status — picked up, on the way, delivered. It is how their system knows what is happening without asking.
Webhook endpoint: Whether the customer’s own software is still accepting the automatic status messages sent to it. If it stops, deliveries keep happening but the customer stops seeing them — which is exactly case 1.
Health grade: One letter (A–F) combining the five measures in this table — on-time, failed, rerouted, cost, and status-feed health — into a single score, so a whole set of customers can be scanned in one pass.
On-time trend: The last 30 days of on-time rate as a single line, to show direction rather than a number. The scale runs 80–100%, so a line pinned flat along the bottom means the rate fell below 80%.
The router: The automatic step that reads every courier’s price and estimated time for an order and picks one. It can be overridden by hand — an override is called a pin.
The desk: This console, and the person watching it. "The desk spotted it" means a human reading this screen noticed, rather than an automatic alert firing.
SLA: The on-time promise written into the customer’s contract — for example, 95% of deliveries on time. Missing it can cost money back.
SLA credit: Money refunded to the customer when the on-time promise in their contract is missed.
Incident: Something broken that needs a person. Sev-1 is worst (customers are losing orders right now), sev-3 is a question that needs a careful answer.

03Where the numbers come from

Every delivery, webhook attempt, quote, timestamp, and dollar figure on this site comes out of one script. Its random number generator (PRNG) is deterministic — it takes a starting number, the seed, and the same seed always produces the same dataset. The clock is frozen at a made-up “now” (A15), so the site is a fixed snapshot anyone can reproduce, not a live feed.

Dataset generation parameters
parameter	value
seed	20260718
prng	mulberry32
generator	scripts/generate-data.ts
generated on (real date)	2026-07-18
simulated “now” (A15)	Fri, May 8, 2026 2:00 PM ET
data window	2026-02-08 → 2026-05-08
total deliveries	128,937
accounts	6 fictional enterprise accounts
providers	5 invented — FleetX, CourierCo, Parcelet, DashNow, Veloway
webhook retry ladder (A1)	6 attempts: +0m, +1m, +5m, +30m, +2h, +6h

Being able to rebuild it is the honesty check: change the seed and every number on the site — including the ones inside the drafted customer emails — changes together and still agrees with itself. No figure is typed into the copy by hand; pages read the generated JSON through a single data interface (src/lib/data-source.ts).

How to verify: npm run generate && npm run build — regenerate the dataset from the seed, then rebuild the static site from it.

04The data is shaped like the real API

The data is invented; its shape is not. Every object carries the same field names, types, and status values Burq’s public documentation specifies, so this console would run against the real API without changing a line. That covers the delivery status lifecycle (all 19 documented statuses), status_history entries, the webhook envelope and its delivery, route, and batch event types, route quotes with costs as integer cents, delivery incidents with the documented status and reason values, and how a reroute behaves (the first delivery is canceled and a new one is created under a new ID). The types in src/types/burq-schema.ts name the exact page each shape came from:

Get Order (OpenAPI) — Order and Delivery resources, the delivery status enum, status_history
https://burq.readme.io/reference/getorderv2
Webhooks — event envelope, delivery/route/batch event types, signature scheme
https://burq.readme.io/reference/webhooks
Pick Provider — RouteQuote resource; cost_of_delivery and burq_fee as integer cents
https://burq.readme.io/reference/pick-provider
Dispatch — dispatch flow and route status progression
https://burq.readme.io/reference/dispatch
Request Quote — async quote job envelope
https://burq.readme.io/reference/request-quote
GET Delivery Incident — delivery_incident resource with its status and reason enums
https://burq.readme.io/v1.3.0/reference/getdeliveryincident
Terminology and Concepts — order vs delivery vs route definitions
https://burq.readme.io/reference/terminology-and-concepts-1
Reroute (guide) — reroute triggers, dashboard states, max allowed price difference
https://burq.readme.io/docs/delivery-rerouting
API Conventions — general request/response conventions
https://burq.readme.io/reference/api-conventions-1

One place the public docs disagree with themselves (A2): the Get Order OpenAPI schema names the status_history timestamp key time, while the Webhooks guide’s JSON example shows created. Where the two public sources disagree, this project follows the versioned OpenAPI schema.

05How the grades are worked out

What gets measured is not invented for this site — it comes from Burq’s own published integration-readiness checklist, “Scale Delivery Operations with Smarter API Integration” (Burq blog). Its criteria: webhook retries and monitoring (“retries are configured, failures are logged, and alerts exist”), a set plan for when things go wrong, a way to fall back to another courier, and being able to report — on-time rate, failure rate, reroute rate, and cost by provider/zone.

Whose standard is what: the things measured above are Burq’s published criteria. How much each one counts, where the letter grades cut off, and the webhook thresholds are this console’s own scoring policy (A9, A10) — reasonable defaults, stated plainly, not Burq policy.

Health score components, weights, and measurement definitions
component	weight	how measured
On-time rate	30%	Share of the last 30 days’ deliveries that arrived within 15 minutes of the time promised when the order was handed to the courier (A6).
Failure rate	20%	Share of deliveries that ended failed or canceled instead of delivered.
Webhook health	25%	Share of status messages the customer’s own server accepted (a 2xx answer) over the last 24 hours: healthy ≥ 99.5%, degraded ≥ 97.0%, failing below — or straight away after 6 messages in a row that used up every retry and never landed (A9).
Reroute rate	10%	Share of deliveries taken back from one courier after dispatch and given to another.
Cost efficiency	15%	All-in cost of one delivery, compared against the median across all six customers, $10.74.

Each part is scored 0–100, then they are added up by weight into one number and given a letter: A ≥ 85, B ≥ 75, C ≥ 65, D ≥ 55, else F (A10). The grade column on the board links back to this section.

06The tables the SQL runs against

Every SQL query on this site runs against the same made-up set of tables (A8): the reporting database an operator would build on their own side by keeping every webhook payload and dispatch log. It is not a Burq product surface — Burq does not expose a SQL interface — but it is the store that the checklist’s reporting requirements imply, and all queries against it are valid runnable-shaped Postgres.

Illustrative ops warehouse tables and columns
table	columns	captures
deliveries	delivery_id, order_ref, account_id, provider_id, zip, status, created_at, pickup_window_end, promised_at, delivered_at, cost_cents, basket_cents	one row per delivery: timing, outcome, cost, basket value
delivery_status_events	delivery_id, account_id, status, occurred_at	append-only log of every status transition
webhook_attempts	event_id, account_id, delivery_id, event_type, attempt, http_status, latency_ms, ts	every webhook POST, including retries, with its HTTP result
dispatch_attempts	order_ref, account_id, zip, provider_id, action, reason_code, price_cents, eta_minutes, ts	quote requests, returns, declines, and dispatches per provider
quotes	order_ref, account_id, zip, provider_id, price_cents, eta_minutes, trailing_on_time, chosen, ts	every provider quote at decision time, with the chosen one flagged

07Everything assumed, listed in full

Every mechanism in this artifact that is not documented in Burq's public docs (burq.readme.io) is listed here, with a one-line rationale. The UI never presents an assumed mechanism as documented Burq behavior; panels that depend on one carry an "illustrative — see ASSUMPTIONS.md" label citing the ID. Everything else on the site traces to a cited doc page (see /methodology).

Full assumptions register from ASSUMPTIONS.md
id	assumption	rationale
A1	Webhook retry schedule: 6 attempts per event at +0s, +1m, +5m, +30m, +2h, +6h after first failure, then the event is dropped.	Burq's blog checklist confirms retries exist ("retries are configured, failures are logged") but no public page specifies counts or intervals; exponential backoff is the standard industry pattern.
A2	`status_history` timestamp key is `time`.	The Get Order OpenAPI schema documents `time`; the Webhooks guide's JSON example shows `created`. Where the two public sources disagree we follow the versioned OpenAPI schema.
A3	Provider decline reason codes (`no_couriers_available`, `capacity_limit_reached`, `zone_not_served`, `vehicle_unavailable`, `pickup_window_unserviceable`).	The docs document dispatch error codes but not per-provider quote-decline reasons; these are invented, modeled on common courier-API vocabulary.
A4	Provider cost curves and zone-level on-time performance for the five fictional providers.	No real provider pricing or performance data is public (or used); curves are invented to make the tradeoffs in Case 3 concrete.
A5	Zone = 5-digit ZIP prefix rollup. Burq quotes per route; grouping metrics by ZIP-code "zone" is an internal analytics convention of this console, not a Burq product feature.	The blog checklist calls for "cost by provider/zone" measurement but doesn't define zones.
A6	On-time definition: delivered ≤ 15 minutes after the dropoff `estimated_arrival_at` communicated at dispatch time.	The docs expose ETAs but no public SLA definition; 15 minutes is a common last-mile grace window.
A7	Late-delivery economics in Case 3: 40% of late deliveries generate a refund averaging $34; 55% generate a support contact costing $11; a routing change only counts as savings above $250/mo materiality.	Burq documents refund outcomes (full / partial / none) but not rates; the arithmetic is illustrative and every input is shown on screen.
A8	Internal events warehouse schema (`deliveries`, `delivery_status_events`, `webhook_attempts`, `dispatch_attempts`, `quotes` tables) used by the SQL panes.	This is the merchant-side/ops-side analytics schema an operator would build from webhook data — it is not a Burq API surface. Documented in full on /methodology.
A9	Webhook endpoint-health scoring: rolling 24h 2xx rate with grade cutoffs (healthy ≥ 99.5%, degraded ≥ 97%, failing below; failing immediately if ≥ 6 consecutive terminal failures).	The blog checklist requires webhook monitoring but defines no thresholds; cutoffs chosen so one dropped event doesn't page anyone but a dead endpoint alerts within an hour.
A10	Composite health grade weights: on-time 30%, failure rate 20%, webhook health 25%, reroute rate 10%, cost efficiency 15%; letter cutoffs A ≥ 85, B ≥ 75, C ≥ 65, D ≥ 55, else F.	The four measured dimensions come from Burq's published checklist; the weights and cutoffs are this console's own scoring policy.
A11	Fallback chain configuration per zone (ordered provider list with per-zone opt-outs).	The docs document auto-reroute on cancellation/delayed assignment and manual provider selection, but not a per-zone fallback-chain config; Case 2 needs one to show where the chain ends.
A12	Stuck-order alert threshold: unassigned > 20 min past pickup window = stuck; ≥ 5 stuck orders in one zone within 60 min = page, and at ≥ 10 you stop re-dispatching one-by-one and call the customer.	Operator judgment values, not Burq policy; the reasoning is narrated in Case 2.
A13	Delivery fee levels ($7–$24 per delivery depending on provider, zone, distance) and per-account basket values.	`cost_of_delivery`/`burq_fee` are documented as cents but no public price list exists; levels are plausible for US last-mile.
A14	SLA credit exposure framed as a % of monthly delivery spend per contract tier.	Enterprise SLA credit structures are standard but account-specific; figures are illustrative.
A15	Simulated clock: the dataset covers 2026-02-08 → 2026-05-08 and "now" inside the console is Friday 2026-05-08 14:00 ET — the Friday before Mother's Day, chosen so the florist incident (Case 2) is live on the board.	Fixed so the seeded generator is fully deterministic; the site is a snapshot, not a live feed.

Generation: scripts/generate-data.ts, seed 20260718, mulberry32 PRNG. Change the seed and every number on the site — including the ones inside the drafted customer emails — regenerates coherently.

08Not affiliated with Burq

Stated in full, because this page exists to be checked:

All data on this site is simulated, produced by the seeded generator described above, and conforms to Burq’s publicly documented API schemas.
It contains no customer data, no production data, and no data obtained from Burq systems.
It uses no Burq brand assets — no logos, wordmarks, or visual design.
References to Burq and links to its public documentation are nominative only — they name the documented API this simulation conforms to, nothing more.
This is an independent project, not affiliated with, endorsed by, or connected to Burq, Inc.
All accounts, providers, contacts, and their names are fictional coinages; any resemblance to real businesses or people — in delivery or any other industry — is coincidental and unintentional.