From 729b31383d819f78a13bbf65383987cb666c8359 Mon Sep 17 00:00:00 2001
From: Michael Kechinov <kechinoff@gmail.com>
Date: Tue, 4 Nov 2025 17:39:57 +0300
Subject: [PATCH] feat: promos for client

Closes #DEV-3408
---
 .../_loyalty.promos.for-client.md.erb         | 84 +++++++++++++++++++
 source/index.html.md                          |  1 +
 2 files changed, 85 insertions(+)
 create mode 100644 source/includes/_loyalty.promos.for-client.md.erb

diff --git a/source/includes/_loyalty.promos.for-client.md.erb b/source/includes/_loyalty.promos.for-client.md.erb
new file mode 100644
index 0000000..235392b
--- /dev/null
+++ b/source/includes/_loyalty.promos.for-client.md.erb
@@ -0,0 +1,84 @@
+## Promotions for a client
+
+> Headers
+
+```
+Content-type: application/json
+```
+
+> Body example
+
+```json
+{
+    "shop_id":        "...",
+    "did":            "...",
+    "seance":         "...",
+    "email":          "...",
+    "phone":          "...",
+    "external_id":    "...",
+    "stream":         "...",
+    "promo_codes":    ["..."],
+    "location_id":    "...",
+    "charge_bonuses": true,
+    "cart_items": [
+      {"product_id": "...", "price": 1000, "quantity": 4},
+      {"product_id": "...", "price": 2000, "quantity": 1}
+    ]
+}
+```
+
+> Request example
+
+```shell
+curl --header "Content-Type: application/json" \
+  --request POST \
+  --data-binary "@data.json" \
+  https://<%= config[:api_endpoint] %>/loyalty/promos/for-client
+```
+
+```javascript
+// Not implemented yet
+```
+```swift
+// Not implemented yet
+```
+```java
+// Not implemented yet
+```
+```kotlin
+// Not implemented yet
+```
+```jsx
+// Not implemented yet
+```
+
+> The above command returns JSON structured like this:
+
+```json
+{
+  "success": true,
+  "payload": [
+    {"id": 1, "name": "...", "description": "...", "badge_label": "...", "badge_color": "..." },
+    {"id": 2, "name": "...", "description": "...", "badge_label": "...", "badge_color": "..." }
+  ]
+}
+```
+
+### HTTP Request
+
+`POST https://<%= config[:api_endpoint] %>/loyalty/promos/for-client`
+
+Returns list of all active promotions for the current user.
+
+| Parameter   | Type     | Required | Description                                                                  |
+|-------------|----------|----------|------------------------------------------------------------------------------|
+| shop_id     | String   | true     | Your API key                                                                 |
+| stream      | String   | false    | Stream to filter promos for different devices. Omit if you don't use streams |
+| location_id | String   | false    | Location ID                                                                  |
+| did*        | string   | false    | Device ID                                                                    |
+| external_id | string   | false    | External ID                                                                  |
+| email       | string 	 | false    | Email                                                                        |
+| phone       | string 	 | false    | Phone                                                                        |
+| loyalty_id  | string 	 | false    | Loyalty ID                                                                   |
+| telegram_id | string 	 | false    | Telegram ID                                                                  |
+| cart_items  | Array    | false    | Current shopping cart                                                        |
diff --git a/source/index.html.md b/source/index.html.md
index 5bf22b2..b761bb0 100644
--- a/source/index.html.md
+++ b/source/index.html.md
@@ -51,6 +51,7 @@ includes:
   - loyalty.checkout.orders-history.md.erb
   - loyalty.promos.md.erb
   - loyalty.promos.index.md.erb
+  - loyalty.promos.for-client.md.erb
   - loyalty.promos.cart.md.erb
   - loyalty.referral.md.erb
   - loyalty.referral.join.md.erb