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 is6..10, you must send a new rating in the 1..5 range in the same PUT — otherwise the request is rejected with400.
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
- Feedback API reference — every endpoint, full schemas, error codes
- Authentication — the
x-guper-authorizationtoken - List query parameters — building filtered list URLs