Events and commercial outcomes
Connect quiz behavior to later order outcomes without claiming that correlation proves impact.
Automatically recorded
| Event | When |
|---|---|
| fit_started | Session created. |
| fit_completed | Valid answers produced a recommendation. |
| recommendation_generated | Recommendation persisted. |
| recommendation_accepted | Session completed with the recommended size. |
| recommendation_overridden | Session completed with a different size. |
Do not send these to POST /events; the API records them transactionally. This prevents retries from inflating quiz and decision counts.
Send storefront and order outcomes
- fit_viewed: the customer sees the size-help entry point.
- add_to_cart and checkout_started: send from the storefront integration through your backend.
- purchase: send from the backend after a confirmed order.
- return_requested and size_exchange: include reason=size or other.
- item_kept: an explicit verified signal; never infer it from missing return data.
curl --fail-with-body -X POST "$METR_API_URL/v1/stores/$STORE_ID/events" \
-H "Authorization: Bearer $METR_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"external_id": "order-123-line-1-return",
"source": "custom-store",
"type": "return_requested",
"product_id": "prd_example",
"variant_id": "var_medium",
"session_id": "fit_example",
"order_id": "order-123",
"line_item_id": "line-1",
"reason": "size",
"quantity": 1,
"occurred_at": "REPLACE_WITH_CURRENT_RFC3339_TIMESTAMP"
}'Identity, attribution and retries
Use stable external_id values for deliveries. The uniqueness boundary is merchant + store + source + external_id. Identical retries return 200 and the original event; changed payloads return 409. First delivery returns 201. occurred_at must be within the previous year and no more than five minutes ahead.
Order outcomes require product_id, variant_id, order_id and line_item_id. Keep order/line IDs stable across purchase, return, exchange and kept signals. session_id is optional for unassisted purchases and delayed outcomes, but include it on a Fit-assisted purchase. If supplied, it must belong to the same product and store. Never attach an event that predates the session.
Metrics and denominators
GET /v1/stores/{store_id}/metrics accepts from/to RFC3339 timestamps. It selects sessions created in [from,to) and observes linked outcomes through the response’s observed_through time. Maximum range: 366 days. Default: last 30 days. Metrics count unique sessions and purchased order lines, not units.
| Rate | Numerator / denominator |
|---|---|
| Quiz completion | Recommended sessions / started sessions |
| Recommendation acceptance | Accepted sessions / recommended sessions |
| Recommendation override | Overridden sessions / recommended sessions |
| Fit-assisted conversion | Recommended sessions with a linked purchase / recommended sessions |
| Size-related return | Purchased lines with a size return / Fit-assisted purchased lines |
| Kept after recommendation | Purchased lines with an explicit kept signal / Fit-assisted purchased lines |
| Exchange for size | Purchased lines with a size exchange / Fit-assisted purchased lines |
A zero denominator returns null. Return and kept windows may be immature, and missing integration events bias rates. Different outcomes may apply to one line over time. These descriptive cohorts do not establish causal conversion lift or return reduction. Use a properly designed randomized experiment for causal claims.