---
feature: Rating the provider
slug: ratings
surface: client
consumer: flutter
version: 1.0.0
status: ready
brd_version: "1.3"
brd_ids: [CUST-021]
business_rules: [BR-28]
decisions: [DEC-19, TD-104, TD-160, TD-162]
schema_tables: [reviews, review_tags, review_tag_links, orders, providers, customers]
screens: "`customer--reviews--*` (SCR-23)"
related_docs: [../provider/ratings.md, ../admin/ratings.md, orders.md]
last_updated: 2026-11-02
---

# Rating the provider — Flutter integration guide (client)

> **Base URL:** `{HOST}/api/v1/client` · Shared rules (headers, envelope, errors, pagination):
> [API_CONVENTIONS.md](../API_CONVENTIONS.md)

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.0.0 | 2026-11-02 | Initial | `GET /review-tags` and `POST /orders/{order}/rating` (rate the provider after completion). | Build the rating sheet (stars, tags, optional comment) and show the Rate button from `can_rate`. |

## Changelog

### 1.0.0 — 2026-11-02

- **Added:** `GET /review-tags`, `POST /orders/{order}/rating`.
- **Changed:** — · **Fixed:** — · **Removed / Deprecated:** —
- **Breaking:** No.
- **App action required:** Build the rating sheet (stars, tags, optional comment) and show the Rate button from `can_rate`.
- **BRD / decisions:** CUST-021, BR-28, DEC-19, TD-104, TD-160, TD-162.

---

## 1. Business summary

After an order is `completed` the customer may rate the provider **once per order** (BR-28): stars 1–5, an optional comment and optional tags (SCR-23). Cancelled and incomplete orders, and package **purchases**, cannot be rated (a package *session* order can). The rating is saved visible, appears on the provider's page and in her feedback history, counts in her average, and joins the admin moderation queue where it may be hidden (ADMIN-019, TD-160). The customer has no private note: that field exists on the provider app only and is refused here.

## 2. User flow and screens

| Step | Screen / widget | Endpoint | Notes |
|------|-----------------|----------|-------|
| 1 | Order details → "Rate" button | `GET /orders/{order}` | Show it only while `can_rate` is `true`; it turns `false` after the rating is saved. |
| 2 | Rating sheet: stars, tags, comment | `GET /review-tags` | Active tags for this direction, in display order. |
| 3 | Submit | `POST /orders/{order}/rating` | 201 with the saved rating. |

## 3. Endpoints

Every key is always present; ids are uuids.

### 3.1 Tags

`GET /api/v1/client/review-tags`

| | |
|---|---|
| Auth | Bearer token · `app:customer` |

**Success — `200`** (tags for customer → provider, active only)

```json
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": {
    "tags": [
      {
        "id": "01a19c08-ff9d-72ff-acb6-1295e69e102d",
        "label": "Sample-obkd01353568"
      },
      {
        "id": "01a19c08-eb63-706b-8e8e-66bd0abd91fe",
        "label": "Punctuality & Timing"
      },
      {
        "id": "01a19c08-eb69-7243-a96c-5adb3b5f1db2",
        "label": "Cleanliness & Sanitization"
      },
      {
        "id": "01a19c08-eb6f-72e5-89df-220c70e143ef",
        "label": "Professionalism & Skill"
      },
      {
        "id": "01a19c08-eb75-7012-a701-1c23e04d0b75",
        "label": "Premium Products"
      },
      {
        "id": "01a19c08-eb7a-701b-b45d-cdf1b5acc7ed",
        "label": "Polite & Friendly"
      },
      {
        "id": "01a19c08-eb7f-735f-b2d0-358b33174367",
        "label": "Neat & Professional Appearance"
      }
    ]
  }
}
```

Postman: `client.review-tags.index` › "200 Tags for my rating direction"

### 3.2 Submit a rating

`POST /api/v1/client/orders/{order}/rating`

| | |
|---|---|
| Auth | Bearer token · `app:customer` |
| Rate limit | `review-submit`, 10 per minute per user (429 `RATE_LIMITED`) |

**Body**

| Field | Type | Required | Rules | Description |
|-------|------|----------|-------|-------------|
| `stars` | int | yes | 1–5 | Whole stars. |
| `comment` | string | no | ≤ 1000 | Public comment, subject to moderation. |
| `private_note` | — | — | prohibited | Not available to customers; sending it is a 422. |
| `tags` | array | no | ≤ 10 uuids | Ids from `GET review-tags`. |

**Success — `201`**

```json
{
  "status": "success",
  "message": "Thank you, your rating was saved.",
  "data": {
    "id": "01a19c09-01fe-728d-abd2-803169e48e6b",
    "order": {
      "id": "01a19c08-ff94-7000-bd7e-ad16623e9fd0",
      "code": "JSH-xdrc55345941"
    },
    "direction": {
      "value": "customer_to_provider",
      "label": "Customer rated provider"
    },
    "stars": 5,
    "comment": "Great",
    "tags": [
      {
        "id": "01a19c08-ff9d-72ff-acb6-1295e69e102d",
        "label": "Sample-obkd01353568"
      }
    ],
    "created_at": "2026-11-02T11:33:18+00:00"
  }
}
```

Postman: `client.orders.rating` › "201 Order rated"

**Errors**

| Case | Response |
|------|----------|
| Invalid input | `422` `VALIDATION_FAILED` — Postman: `client.orders.rating` › "422 Stars out of range" |
| Order not completed (or a package purchase) | `422` `REVIEW_ORDER_NOT_RATABLE` — Postman: `client.orders.rating` › "422 Order is not completed" |
| Already rated this order | `409` `REVIEW_ALREADY_SUBMITTED` — Postman: `client.orders.rating` › "409 Order already rated" |
| An inactive tag or one of the other direction | `422` `REVIEW_TAG_INVALID` |
| Not her order | `404` (never confirmed to a stranger) |
| Too many attempts | `429` `RATE_LIMITED` — Postman: `client.orders.rating` › "429 Too many rating attempts" |

## 4. Business rules the backend enforces

- **BR-28:** only a `completed` order, one rating per order per direction (unique index backstop; two taps write one rating, the second answers 409).
- The order row is locked before the checks, so a double tap is safe.
- The reviewee's `rating_avg` / `rating_count` are recomputed from visible ratings after every save.
- Hidden ratings never count and never show (TD-160).

## 5. Notifications

None. A rating does not notify the rated party.

## 6. Integration checklist

- [ ] Show **Rate** only while the order's `can_rate` is `true`.
- [ ] Load `GET /review-tags` once per sheet; send tag ids back as uuids.
- [ ] Treat 409 as "already rated" and refresh the order.
- [ ] Do not send `private_note`.

## 7. Acceptance scenarios and open decisions

AC-CUST-021 (rating after completion, optional comment, one per order, cancelled orders refused). Tests: `tests/Feature/Api/V1/Shared/RatingCycleTest.php`.

Open: DEC-19 *customer submission limits* stay open — only the schema's one-per-direction rule applies (TD-104). Provider → driver rating is not built.
