# "حسم" (sale discount) on the checkout and order summary (app update)

**For:** mobile app developer · **Date:** 2026-10-24 · **Branch:** `feat/checkout-sale-discount-line-2026-10-24`

No breaking change: no endpoint, URL, request body or existing key changed. Only **new keys** were added. Old app builds keep working and simply don't show the new row.

## 1. What to show

When products in the cart / order are on sale (a product discount, a flash deal, or a struck-out price), the summary now shows how much the sale took off, in its own row named **"حسم"**, right after the coupon row **"القسيمة"**:

```
المجموع الفرعي        48,000 ل.س    ← subtotal BEFORE the sale (new key)
الشحن                  5,000 ل.س
القسيمة              − 2,000 ل.س    ← existing coupon row
حسم                  − 4,000 ل.س    ← NEW
─────────────────────────────
الإجمالي              47,000 ل.س    ← unchanged
```

Rules:

- Show the **حسم** row only when its amount is **> 0**.
- When you show it, the subtotal row must show the **new "before sale" key**, not the old subtotal. Otherwise the rows don't add up, because the old subtotal already has the sale taken off.
- **The total does not change.** Keep reading the same total key as today.
- The website does exactly this on `/checkout`, the cart page and the order page.

Always: `subtotal_before_sale − sale_discount = subtotal` (the old key).

## 2. Checkout / cart: `POST /api/v2/cart-summary`

The same body also arrives inside `POST /api/v2/checkout/overview` → `cart_summary`, unchanged otherwise.

New keys:

| Key | Type | Meaning |
|---|---|---|
| `sale_discount` | string | the sale amount, formatted (e.g. `"4,000 ل.س"`) → value of the **حسم** row |
| `sale_discount_value` | number | the same amount in Syrian pounds, a number (like `grand_total_value`): use it for `> 0` |
| `sub_total_before_sale` | string | the products before the sale, formatted → value of the subtotal row when حسم is shown |

Existing keys are unchanged: `sub_total` (after the sale), `discount` (= the coupon, **القسيمة**), `tax`, `shipping_cost`, `grand_total`, `grand_total_value`, `coupon_code`, `coupon_applied`.

```json
{
  "sub_total": "44,000 ل.س",
  "tax": "0 ل.س",
  "shipping_cost": "5,000 ل.س",
  "discount": "2,000 ل.س",
  "grand_total": "47,000 ل.س",
  "grand_total_value": 47000,
  "coupon_code": "SAVE",
  "coupon_applied": true,
  "sale_discount": "4,000 ل.س",
  "sale_discount_value": 4000,
  "sub_total_before_sale": "48,000 ل.س"
}
```

An empty cart answers `sale_discount: "0 ل.س"`, `sale_discount_value: 0`, `sub_total_before_sale: "0 ل.س"`.

## 3. Order page

### 3.1 `GET /api/v2/purchase-history/combined/{order_id}` (whole checkout, `docs/api/combined-orders.md`)

New keys next to `subtotal` / `coupon_discount`, in the usual amount format `{"amount": <SYP number>, "formatted": "<text>"}`:

| Key | Meaning |
|---|---|
| `sale_discount` | the sale taken off the checkout's products → **حسم** row |
| `subtotal_before_sale` | the products before the sale → subtotal row when حسم is shown |

```json
"subtotal": {"amount": 44000, "formatted": "44,000 ل.س"},
"subtotal_before_sale": {"amount": 48000, "formatted": "48,000 ل.س"},
"sale_discount": {"amount": 4000, "formatted": "4,000 ل.س"},
"coupon_discount": {"amount": 2000, "formatted": "2,000 ل.س"},
"shipping": {"amount": 5000, "formatted": "5,000 ل.س"},
"total": {"amount": 47000, "formatted": "47,000 ل.س"}
```

`subtotal + tax + shipping − coupon_discount = total` still holds as before.

### 3.2 `GET /api/v2/purchase-history-details/{id}` (old per-order endpoint)

Two new formatted strings, for **this seller order's** products (the same scope as its `subtotal`):

| Key | Meaning |
|---|---|
| `sale_discount` | e.g. `"4,000 ل.س"` → **حسم** row |
| `subtotal_before_sale` | e.g. `"48,000 ل.س"` → subtotal row when حسم is shown |

This endpoint only returns strings, so to decide whether to show the row, compare `subtotal_before_sale` with `subtotal`: different means there is a sale. Or move to 3.1, which also gives `amount`.

## 4. Things to know

- **Cancelled and returned products are left out**, like every other total. Never add up `lines` yourself.
- **Orders placed before 2026-10-10 show no حسم** (`sale_discount` = 0). The server only started keeping each product's price before the sale on that date, and it does not guess it from today's prices.
- **حسم is per order, frozen.** On an order it is what the sale was when the order was placed. In the cart it is today's sale, so it changes when a sale starts or ends.
- Amounts are in Syrian pounds at the order's rate, already rounded. Show `formatted` as is.
- Label: write **"حسم"** in Arabic. In English the website uses **"Sale discount"** (translation key `sale_discount`).