Sign in
.md

Feedback (CSAT / NPS)

Guper's feedback endpoints let you record one review per order, in either of the two industry-standard scales:

  • CSAT — Customer Satisfaction. The customer rates from 1 to 5, usually answering “How satisfied were you with this order?”. Reporting is the average score, or the share of 4..5 (satisfied).
  • NPS — Net Promoter Score. The customer rates from 0 to 10, usually answering “How likely are you to recommend us to a friend?”. Reporting splits respondents into detractors (0..6), passives (7..8) and promoters (9..10); the score is % promoters − % detractors.

You pick the scale per review via the required type field — the same endpoint handles both, and the same organization can mix them in different flows (e.g. CSAT after support, NPS after delivery).

Quick reference

CSAT NPS
type "csat" "nps"
Allowed rating 1..5 0..10
Typical question How satisfied? How likely to recommend?
Common cut points 4..5 = satisfied 9..10 = promoter · 0..6 = detractor
Score formula avg(rating) (%9..10) − (%0..6)

The full flow

┌────────────────────┐     ┌──────────────────────┐     ┌────────────────────┐
│ 1. (Optional)      │     │ 2. Customer answers  │     │ 3. Read it back    │
│    Create a        │ →   │    → POST review     │ →   │    /review/byOrder │
│    category        │     │    (csat OR nps)     │     │    or filtered list│
└────────────────────┘     └──────────────────────┘     └────────────────────┘

Step 1 — (Optional) Define categories

Categories are an optional taxonomy that groups reviews around what you actually want to measure (e.g. delivery, product, service). Most organizations start with no categories at all — every review is uncategorized (categoryId: null). Adopt a catalog when you need to slice reports by topic.

POST /api/register/feedback/category
{
    "slug":        "delivery",
    "name":        "Delivery",
    "description": "Evaluates the delivery experience."
}

slug is unique per organization. Keep it short, stable, and snake-cased — it usually doesn't change once analytics dashboards rely on it.

Step 2 — Record the review

POST /api/register/feedback/review
{
    "personId":   12345,
    "orderId":    "ORD-789",
    "type":       "csat",       /* or "nps" */
    "rating":     5,             /* must fit the type's range */
    "comment":    "Arrived earlier than promised, packed perfectly.",
    "categoryId": 1,             /* optional */
    "source":     "journey"      /* optional; defaults to "journey" */
}

Required fields: personId, orderId, type, rating, comment. The schema enforces one review per (organization, orderId) — a second POST for the same order is rejected with 409 Conflict. Use PUT /review/{id} to amend instead.

Step 3 — Read it back

Two read patterns are useful in day-to-day flows:

# Did this order get a review yet?
GET /api/register/feedback/review/byOrder/ORD-789
# 200 — review exists
# 404 — no review yet; this is your cue to invite the customer
# Pull promoters from the last campaign
GET /api/register/feedback/review?q[type][]=nps&q[rating][GTE]=9

Listing supports the standard q[col][OP]=value grammar — see List query parameters.

Editing a review

PUT /api/register/feedback/review/{id} patches only the fields you send. Two non-obvious rules apply when the discriminator changes:

  • csat → nps is always safe: the original rating (1..5) still fits the new range (0..10), but you may overwrite it with a higher score.
  • nps → csat is only safe when the existing rating is 1..5. If the original NPS rating is 6..10, you must send a new rating in the 1..5 range in the same PUT — otherwise the request is rejected with 400.

Validation rules

Rule Status
Missing type, personId, orderId, rating or comment 400 Bad Request
type is not csat or nps 400 Bad Request
rating outside the range for the chosen type (csat: 1..5 · nps: 0..10) 400 Bad Request
comment empty or whitespace only 400 Bad Request
categoryId does not belong to this organization 400 Bad Request
Another review already exists for (organization, orderId) 409 Conflict

Choosing CSAT vs NPS

There is no “right” answer — the scales answer different questions:

  • Use CSAT when you want to measure a specific transaction (“Was this delivery good?”). The 1..5 scale is fast to answer and easy to explain.
  • Use NPS when you want a loyalty signal (“Would you recommend us?”). The 0..10 scale lets you separate active fans from passively satisfied customers.

Many programs mix both: a quick CSAT right after the order completes, an NPS pulse a week later. Because every review carries its own type, you can drive both flows through the same endpoint and filter them apart at read time.

See also