---
title: 'Feedback (CSAT / NPS)'
description: 'Collect one satisfaction review per order — either CSAT (1..5) or NPS (0..10) — and read them back for reporting.'
---

# 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.

```bash
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

```bash
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:

```bash
# 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
```

```bash
# 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](/docs/{lang}/guides/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

- [Feedback API reference](/docs/{lang}/api-reference/register/feedback) — every endpoint, full schemas, error codes
- [Authentication](/docs/{lang}/guides/authentication) — the `x-guper-authorization` token
- [List query parameters](/docs/{lang}/guides/list-query-parameters) — building filtered list URLs
