@wix/agent-skills 1.15.1 → 1.16.0

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-create-discount-rule.md

@@ -22,7 +22,7 @@ layer: config
 
 ## Critical: `discounts` structure
 
-**The API always returns the full normalized structure.** Never assume a simplified form. Each discount entry looks like:
+**The API always returns the full normalized structure**, `values` wrapper included. Never assume a simplified form. Each entry of `discounts.values` looks like:
 
 ```json
 {
@@ -38,14 +38,12 @@ layer: config
       }
     ]
   },
-  "discount": {
-    "discountType": "PERCENTAGE",
-    "percentage": 20
-  }
+  "discountType": "PERCENTAGE",
+  "percentage": 20
 }
 ```
 
-When updating a rule, always use the `discounts` array as returned from the query/get, modifying only the specific fields you need. **Do not reconstruct from scratch unless creating a new rule.**
+When updating a rule, always reuse the `discounts.values` entries as returned from the query/get, modifying only the specific fields you need. **Do not reconstruct from scratch unless creating a new rule.**
 
 ---
 
@@ -53,8 +51,6 @@ When updating a rule, always use the `discounts` array as returned from the quer
 
 **Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query`
 
-> **Paging**: This API uses **cursor paging** (`cursorPaging`), not offset paging. Using `paging` instead of `cursorPaging` will fail.
-
 **Request** — list all rules:
 ```json
 {
@@ -93,7 +89,7 @@ Filterable fields: `id`, `name`, `active`, `revision`, `created_date`, `updated_
         "start": "2026-06-01T00:00:00.000Z",
         "end": "2026-08-31T23:59:59.000Z"
       },
-      "discounts": [
+      "discounts": { "values": [
         {
           "targetType": "SPECIFIC_ITEMS",
           "specificItemsInfo": {
@@ -107,12 +103,10 @@ Filterable fields: `id`, `name`, `active`, `revision`, `created_date`, `updated_
               }
             ]
           },
-          "discount": {
-            "discountType": "PERCENTAGE",
-            "percentage": 10
-          }
+          "discountType": "PERCENTAGE",
+          "percentage": 10
         }
-      ]
+      ] }
     }
   ],
   "pagingMetadata": {
@@ -170,7 +164,7 @@ When a discount *isn't* applying as expected, see [Troubleshoot: Discount Not Ap
       "start": "2026-05-01T00:00:00.000Z",
       "end": "2026-05-03T23:59:59.000Z"
     },
-    "discounts": [
+    "discounts": { "values": [
       {
         "targetType": "SPECIFIC_ITEMS",
         "specificItemsInfo": {
@@ -184,15 +178,10 @@ When a discount *isn't* applying as expected, see [Troubleshoot: Discount Not Ap
             }
           ]
         },
-        "discount": {
-          "discountType": "PERCENTAGE",
-          "percentage": 20
-        }
+        "discountType": "PERCENTAGE",
+        "percentage": 20
       }
-    ],
-    "settings": {
-      "appliesTo": "ALL_ITEMS"
-    }
+    ] }
   }
 }
 ```
@@ -203,7 +192,7 @@ When a discount *isn't* applying as expected, see [Troubleshoot: Discount Not Ap
   "discountRule": {
     "name": "Summer Collection Sale",
     "active": true,
-    "discounts": [
+    "discounts": { "values": [
       {
         "targetType": "SPECIFIC_ITEMS",
         "specificItemsInfo": {
@@ -220,15 +209,10 @@ When a discount *isn't* applying as expected, see [Troubleshoot: Discount Not Ap
             }
           ]
         },
-        "discount": {
-          "discountType": "PERCENTAGE",
-          "percentage": 15
-        }
+        "discountType": "PERCENTAGE",
+        "percentage": 15
       }
-    ],
-    "settings": {
-      "appliesTo": "ALL_ITEMS"
-    }
+    ] }
   }
 }
 ```
@@ -243,7 +227,7 @@ When a discount *isn't* applying as expected, see [Troubleshoot: Discount Not Ap
   "discountRule": {
     "name": "$5 Off Selected Items",
     "active": true,
-    "discounts": [
+    "discounts": { "values": [
       {
         "targetType": "SPECIFIC_ITEMS",
         "specificItemsInfo": {
@@ -258,15 +242,10 @@ When a discount *isn't* applying as expected, see [Troubleshoot: Discount Not Ap
             }
           ]
         },
-        "discount": {
-          "discountType": "FIXED_AMOUNT",
-          "fixedAmount": "5.00"
-        }
+        "discountType": "FIXED_AMOUNT",
+        "fixedAmount": "5.00"
       }
-    ],
-    "settings": {
-      "appliesTo": "ALL_ITEMS"
-    }
+    ] }
   }
 }
 ```
@@ -287,7 +266,7 @@ Always fetch the rule first (via Get or Query), then modify only the fields you
   "discountRule": {
     "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
     "revision": "1",
-    "discounts": [
+    "discounts": { "values": [
       {
         "targetType": "SPECIFIC_ITEMS",
         "specificItemsInfo": {
@@ -301,12 +280,10 @@ Always fetch the rule first (via Get or Query), then modify only the fields you
             }
           ]
         },
-        "discount": {
-          "discountType": "PERCENTAGE",
-          "percentage": 25
-        }
+        "discountType": "PERCENTAGE",
+        "percentage": 25
       }
-    ]
+    ] }
   },
   "mask": { "paths": ["discounts"] }
 }
@@ -330,8 +307,8 @@ Always fetch the rule first (via Get or Query), then modify only the fields you
 
 The safe pattern for "find a rule by name and update its percentage":
 
-1. Query with name filter → get the rule's `id`, `revision`, and `discounts` array
-2. Modify only the `discount.percentage` inside each discount entry, keeping all other fields intact
+1. Query with name filter → get the rule's `id`, `revision`, and `discounts.values` entries
+2. Modify only `percentage` on each entry, keeping all other fields intact
 3. PATCH with the modified `discounts` and `mask: { paths: ["discounts"] }`
 
 **Step 5a — Query by name**:
@@ -349,29 +326,27 @@ Extract from response: `discountRules[0].id`, `discountRules[0].revision`, `disc
 
 **Step 5b — Update percentage** (modify the returned discounts in-place):
 
-Take the `discounts` array from the query response and update only `discount.percentage` on each entry:
+Take the `discounts.values` entries from the query response and update only `percentage` on each entry:
 ```json
 PATCH https://www.wixapis.com/ecom/v1/discount-rules/{id}
 {
   "discountRule": {
     "id": "<id from query>",
     "revision": "<revision from query>",
-    "discounts": [
+    "discounts": { "values": [
       {
         "targetType": "SPECIFIC_ITEMS",
         "specificItemsInfo": { "<scopes unchanged from query response>" },
-        "discount": {
-          "discountType": "PERCENTAGE",
-          "percentage": 10
-        }
+        "discountType": "PERCENTAGE",
+        "percentage": 10
       }
-    ]
+    ] }
   },
   "mask": { "paths": ["discounts"] }
 }
 ```
 
-> **Important**: Copy `targetType`, `specificItemsInfo.scopes` verbatim from the query response — do not reconstruct them. Only change `discount.discountType` and `discount.percentage`/`discount.fixedAmount`.
+> **Important**: Copy `targetType`, `specificItemsInfo.scopes` verbatim from the query response — do not reconstruct them. Only change `discountType` and `percentage`/`fixedAmount`, keeping them at the entry root.
 
 ---
 
@@ -403,12 +378,11 @@ To delete permanently:
 | `active` | Yes | Whether the rule is currently applied |
 | `activeTimeInfo.start` | No | ISO 8601 start time. Omit for immediate activation |
 | `activeTimeInfo.end` | No | ISO 8601 end time. Omit for no expiration |
-| `discounts[].targetType` | Yes | Always `"SPECIFIC_ITEMS"` for standard rules |
-| `discounts[].specificItemsInfo.scopes[]` | Yes | Array of scope objects — see Scope types below |
-| `discounts[].discount.discountType` | Yes | `"PERCENTAGE"` or `"FIXED_AMOUNT"` or `"FIXED_PRICE"` |
-| `discounts[].discount.percentage` | If PERCENTAGE | Integer 1-100 |
-| `discounts[].discount.fixedAmount` | If FIXED_AMOUNT | Decimal string (e.g., `"5.00"`) |
-| `settings.appliesTo` | Yes on create | Always `"ALL_ITEMS"` |
+| `discounts.values[].targetType` | Yes | Always `"SPECIFIC_ITEMS"` for standard rules |
+| `discounts.values[].specificItemsInfo.scopes[]` | Yes | Array of scope objects — see Scope types below |
+| `discounts.values[].discountType` | Yes | `"PERCENTAGE"` or `"FIXED_AMOUNT"` or `"FIXED_PRICE"` — at the entry root, not inside a `discount` object |
+| `discounts.values[].percentage` | If PERCENTAGE | Number 0.1-100 |
+| `discounts.values[].fixedAmount` | If FIXED_AMOUNT | Decimal string (e.g., `"5.00"`) |
 | `revision` | On update/delete | Must match current value — fetch first |
 | `mask.paths[]` | On update | Recommended — list fields being changed (e.g., `["discounts"]`, `["active"]`) |
 
@@ -488,9 +462,9 @@ The recommendation's `scope` field maps to the API's internal scope structure. T
 
 | Recommendation `discountType` | API field to set | Value format |
 |---|---|---|
-| `PERCENTAGE` | `discount.percentage` | Integer (e.g., `15`) |
-| `FIXED_AMOUNT` | `discount.fixedAmount` | String (e.g., `"5.00"`) |
-| `FIXED_PRICE` | `discount.fixedPrice` | String (e.g., `"29.99"`) |
+| `PERCENTAGE` | `discounts.values[].percentage` | Integer (e.g., `15`) |
+| `FIXED_AMOUNT` | `discounts.values[].fixedAmount` | String (e.g., `"5.00"`) |
+| `FIXED_PRICE` | `discounts.values[].fixedPrice` | String (e.g., `"29.99"`) |
 
 All discount entries use `targetType: "SPECIFIC_ITEMS"` with the scope wrapped in `specificItemsInfo.scopes[]`.
 
@@ -580,18 +554,6 @@ Triggers determine WHEN the discount activates. They are built from the recommen
 | `endDate` is a date string | Convert to ISO 8601 timestamp: `activeTimeInfo.end` |
 | `endDate` is empty `""` | Omit `activeTimeInfo.end` — rule has no expiration |
 
-### Settings
-
-All recommendation-created rules use these fixed settings:
-```json
-{
-  "settings": {
-    "appliesTo": "ALL_ITEMS",
-    "indexOptIn": true
-  }
-}
-```
-
 ---
 
 ## Error Handling
@@ -601,6 +563,8 @@ All recommendation-created rules use these fixed settings:
 | `DISCOUNT_RULE_NOT_FOUND` | The discount rule ID doesn't exist | Re-query discount rules to get current IDs |
 | `REVISION_MISMATCH` | The `revision` doesn't match the current version | Re-fetch the rule to get the latest revision, then retry |
 | `INVALID_DISCOUNT_TYPE` | Unsupported discount type | Use `PERCENTAGE` or `FIXED_AMOUNT` |
+| `Expected an object` (400) | `discounts` sent as a bare array | Wrap the entries — `"discounts": { "values": [ … ] }` |
+| `DISCOUNT_TYPE_AND_DISCOUNT_VALUE_MISMATCH` | `discountType` and the value field nested inside a `discount` object | Move both to the discount entry root, alongside `targetType` |
 | Both `productIds` and `categoryIds` set | Scope mutual exclusivity violation | Use only one: ITEMS with productIds OR CATEGORY with categoryIds |
 | `productIds` empty when scope is ITEMS | Missing required IDs | Query products and provide at least 1 product UUID |
 | `categoryIds` empty when scope is CATEGORY | Missing required IDs | Call getCategoryIds to convert category names to GUIDs |

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-bundle-and-save.md

@@ -1,6 +1,6 @@
 ---
 name: "Flow: Bundle and Save"
-description: BUNDLE_AND_SAVE sub-flow — load [Goal: Drive Cross-Sells] FIRST (it owns classification and routing); this is a sub-step, NOT a direct entry from README.
+description: "BUNDLE_AND_SAVE sub-flow — load [Goal: Drive Cross-Sells] FIRST (it owns classification and routing); this is a sub-step, NOT a direct entry from README."
 ---
 # Flow: Bundle & Save Campaign
 

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-stock-mover.md

@@ -1,6 +1,6 @@
 ---
 name: "Flow: Stock Mover"
-description: Stock-mover clearance sub-flow — load [Goal: Clear Inventory] FIRST (it owns the routing); this is a sub-step.
+description: "Stock-mover clearance sub-flow — load [Goal: Clear Inventory] FIRST (it owns the routing); this is a sub-step."
 ---
 # Flow: Stock Mover Clearance
 

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-upsell-boost.md

@@ -1,6 +1,6 @@
 ---
 name: "Flow: Upsell Boost"
-description: UPSELL_BOOST sub-flow — load [Goal: Increase AOV] FIRST (it owns classification and routing); this is a sub-step, NOT a direct entry from README.
+description: "UPSELL_BOOST sub-flow — load [Goal: Increase AOV] FIRST (it owns classification and routing); this is a sub-step, NOT a direct entry from README."
 ---
 # Flow: Upsell Boost Campaign
 

package/skills/wix-manage/references/ecommerce/recommend-ecommerce-strategy.md

@@ -1,6 +1,6 @@
 ---
 name: "Recommend: eCommerce Strategy"
-description: Unified eCommerce recommendation skill — analyzes site data across ALL domains (discounts, shipping, and future domains) and generates up to 5 actionable recommendations. Single entry point for any "help my business" request. Tracking is built-in.
+description: "Unified eCommerce recommendation skill — analyzes site data across ALL domains (discounts, shipping, and future domains) and generates up to 5 actionable recommendations. Entry point for requests about earning more from the visitors a store already has: sales, promotions, discounts, coupons, clearance, holiday deals, AOV, shipping. Out of scope — traffic acquisition (SEO, ads, social, content); route \"grow my traffic\" requests to marketing instead. Tracking is built-in."
 layer: R
 references:
   - name: "API: Recommendation Tracking"
@@ -21,19 +21,25 @@ references:
   - name: "Setup: Coupons"
     path: ecommerce/setup-coupons.md
     load: false
+  - name: "Goal: Sell Gift Cards"
+    path: ecommerce/gift-cards/ecom-gift-cards-goal-sell-gift-cards.md
+    load: false
 ---
 # Recommend: eCommerce Strategy
 
+> 🚫 **Out of scope — traffic acquisition.** This skill recommends discounts and shipping only: levers that earn more from the visitors a store already has. If the merchant is asking how to *grow* traffic — SEO, ads, social, content — stop here and route them to marketing. Do NOT gather site data, do NOT generate recommendations, and do NOT report "missing required site data" — the request simply is not this skill's job.
+
 > ⛔ **MANDATORY PRE-STEP — do this BEFORE Step 1 (before any API call).**
 >
-> Classify the merchant's request and immediately call `ReadFullDocsArticle` on the matching goal skill. Do NOT gather data first — the goal skill tells you which metrics to pull and what guardrails to apply.
+> Classify the merchant's request and immediately read the full article for the matching goal skill. Do NOT gather data first — the goal skill tells you which metrics to pull and what guardrails to apply.
 >
-> | Merchant intent | Goal to load |
+> | Merchant intent | Goal to read |
 > |---|---|
-> | Holiday / event / date mentioned | `ReadFullDocsArticle` → [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-seasonal-revenue) |
-> | "increase AOV", "spend more", "upsell", "boost sales", generic sales improvement | `ReadFullDocsArticle` → [Goal: Increase AOV](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-increase-aov) |
-> | "clear inventory", "overstock", "clearance", "slow-moving" | `ReadFullDocsArticle` → [Goal: Clear Inventory](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-clear-inventory) |
-> | "bundle", "cross-sell", "buy together", "more items per order" | `ReadFullDocsArticle` → [Goal: Drive Cross-Sells](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-drive-cross-sells) |
+> | Holiday / event / date mentioned | [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-seasonal-revenue) |
+> | "increase AOV", "spend more", "upsell", "boost sales", generic sales improvement | [Goal: Increase AOV](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-increase-aov) |
+> | "clear inventory", "overstock", "clearance", "slow-moving" | [Goal: Clear Inventory](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-clear-inventory) |
+> | "bundle", "cross-sell", "buy together", "more items per order" | [Goal: Drive Cross-Sells](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-drive-cross-sells) |
+> | "sell gift cards", "add a gift card", "gift card amounts / denominations" | [Goal: Sell Gift Cards](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-sell-gift-cards) |
 >
 > After loading the goal skill, continue from Step 1 below. The goal skill will instruct you to load the matching flow skill — follow those instructions too.
 >
@@ -49,8 +55,9 @@ references:
 3. **Execute every step in order.** Do not skip steps. Do not merge steps. Do not answer "in the meantime."
 4. **Use ONLY data returned by API calls.** Never substitute reasoning, general knowledge, or doc summaries for live data. Every number you cite in `reasoning` MUST come directly from an API response — do NOT assume, infer, or fabricate data.
 5. **If a call fails or is blocked, report the exact blocker.** Do not work around it with assumptions.
-6. **All API calls use `CallWixSiteAPI`.** The internal tool names (getSiteData, getCatalogAnalytics, etc.) are NOT directly callable.
-7. **Generate recommendations across ALL relevant domains** — not just discounts. Consider shipping, discounts, and any other domain that the data supports.
+6. **Issue every API call as an authenticated request in the merchant's site context, using exactly the endpoints given below.** The internal service method names (getSiteData, getCatalogAnalytics, etc.) are NOT directly callable — only these HTTP endpoints are.
+7. **Generate recommendations across ALL relevant domains** — not just discounts. Consider shipping, discounts, gift cards, and any other domain that the data supports.
+8. **NEVER present a recommendation you have not persisted.** `BatchCreate` (Step 8) is mandatory for every domain — discounts, shipping, gift cards — unless the merchant said `SKIP_TRACKING`. Presenting an unpersisted recommendation means the merchant cannot approve it, so the whole run is wasted. Do not treat Step 8 as a closing formality: it is the step that makes the output actionable.
 
 ---
 
@@ -58,7 +65,7 @@ references:
 
 **MANDATORY — do this first.**
 
-If you don't already have a `siteId`, call `ListWixSites` to find it.
+If you don't already have a `siteId`, list the merchant's Wix sites to find it.
 
 If the merchant mentioned a site name, match it. If only one site exists, auto-select it. Store the `siteId` — every subsequent API call requires it.
 
@@ -70,15 +77,12 @@ If the merchant mentioned a site name, match it. If only one site exists, auto-s
 
 **MANDATORY — do NOT skip unless the user said `SKIP_TRACKING` or "don't track".**
 
-Query the tracking database for existing recommendations on this site:
+Query the tracking database for existing recommendations on this site.
 
-```
-CallWixSiteAPI(
-  url: "https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/query",
-  method: "POST",
+**Endpoint:** `POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/query`
 
-  body: { "query": { "filter": {}, "cursorPaging": { "limit": 50 } } }
-)
+```json
+{ "query": { "filter": {}, "cursorPaging": { "limit": 50 } } }
 ```
 
 **Use the returned history to inform your analysis:**
@@ -99,24 +103,21 @@ If the query returns empty results or fails, continue — this is a fresh sessio
 
 **MANDATORY API CALL — do not skip.**
 
-```
-CallWixSiteAPI(
-  url: "https://www.wix.com/wix-profile-client/v4/profile/metasite",
-  method: "POST",
-
-  body: {
-    "fields": [
-      "language",
-      "merchant_business_country",
-      "suggested_main_industry",
-      "suggested_sub_industry",
-      "last_30_days_distinct_visitors",
-      "last_30_days_orders_count",
-      "online_gpv_last_30_days",
-      "payment_currency"
-    ]
-  }
-)
+**Endpoint:** `POST https://www.wix.com/wix-profile-client/v4/profile/metasite`
+
+```json
+{
+  "fields": [
+    "language",
+    "merchant_business_country",
+    "suggested_main_industry",
+    "suggested_sub_industry",
+    "last_30_days_distinct_visitors",
+    "last_30_days_orders_count",
+    "online_gpv_last_30_days",
+    "payment_currency"
+  ]
+}
 ```
 
 **Available fields:**
@@ -181,6 +182,7 @@ Based on the merchant's request AND the site data, determine which domains to an
 |---|---|---|
 | **DISCOUNTS** | Merchant mentions sales, promotions, revenue, AOV, clearance, holidays, coupons. **Also activate if no specific domain is mentioned** (default). | Always — site data contains discount metrics |
 | **SHIPPING** | Merchant mentions shipping, delivery, checkout conversion, cart abandonment. **Also activate proactively** if site data suggests shipping issues. | High visitors + low orders may indicate shipping friction |
+| **GIFT_CARDS** | **Explicit gift-card intent only** — the merchant mentions gift cards, gift vouchers, or gift card amounts. Do **not** activate this domain on a generic "boost my sales" request: it costs a gift-card-product lookup and a goal-skill load for a lever the merchant didn't ask about. | Merchant named gift cards |
 
 **Priority rule**: If the merchant mentions a specific holiday/event/date, the DISCOUNTS domain MUST use the **SEASONAL** strategy — even if other signals like "boost sales" or "increase revenue" could match other goals. Holidays are time-sensitive and take priority over general intent.
 
@@ -192,7 +194,7 @@ Based on the merchant's request AND the site data, determine which domains to an
 
 ## Step 4b: Load domain-specific goal skills
 
-**MANDATORY — load the matching goal skill(s) now using `ReadFullDocsArticle`.** These contain detailed strategy logic, KPIs, margin tiers, campaign window calculations, and guardrails that you MUST follow.
+**MANDATORY — read the full article for the matching goal skill(s) now.** These contain detailed strategy logic, KPIs, margin tiers, campaign window calculations, and guardrails that you MUST follow.
 
 **For DISCOUNTS domain — classify the discount goal and load it:**
 
@@ -204,6 +206,8 @@ Based on the merchant's request AND the site data, determine which domains to an
 | BUNDLE_AND_SAVE | "bundle", "cross-sell", "buy together" | [Goal: Drive Cross-Sells](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-drive-cross-sells) |
 | Generic (no clear goal) | "boost sales", ambiguous | Default to SEASONAL if holiday nearby, else UPSELL_BOOST |
 
+**For GIFT_CARDS domain — load [Goal: Sell Gift Cards](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-sell-gift-cards).** It owns the existing-product gate (a site supports only one gift card product), eligibility, denomination sizing from AOV / catalog prices, the expiry policy, and the mapping onto the real create call. Do not size gift card amounts without it.
+
 **For SHIPPING domain — load the same goal as discounts.** Shipping flows (free shipping threshold, rate optimization) serve the same business goals as discount flows. Load the matching discount goal above — it now includes shipping flow references.
 
 **The goal skill will instruct you to load flow and guardrail skills** — follow those instructions. This chain provides the detailed execution logic you need for high-quality recommendations.
@@ -225,8 +229,8 @@ Based on the merchant's request AND the site data, determine which domains to an
 
 **If unclear, ask:** "Would you like this to apply automatically to everyone, or as a coupon code?"
 
-**If COUPON is selected**, load the coupon setup reference with `ReadFullDocsArticle`:
-[Setup: Coupons](https://dev.wix.com/docs/api-reference/business-solutions/coupons)
+**If COUPON is selected**, read the full article for the coupon setup reference:
+[Pricing: Create Coupon](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-coupon)
 
 ---
 
@@ -238,15 +242,13 @@ Call both APIs concurrently:
 
 ### Call 1: GetCatalogAnalytics
 
+**Endpoint:** `POST https://manage.wix.com/recommendations/v1/recommendations/get-catalog-analytics-tool`
+
 ```
-CallWixSiteAPI(
-  url: "https://manage.wix.com/recommendations/v1/recommendations/get-catalog-analytics-tool",
-  method: "POST",
-  body: {
-    "aggregates": <see table below>,
-    "minMarginPct": 0.15
-  }
-)
+{
+  "aggregates": <see table below>,
+  "minMarginPct": 0.15
+}
 ```
 
 Valid `aggregates` values: `op` ∈ `count|sum|avg|min|max|stddev|quantiles` · `field` ∈ `quantity|price|cost|profit|profitMargin|ordersCount` · `q` required only for `quantiles` (array of 0.0–1.0, max 20)
@@ -284,18 +286,16 @@ Valid `aggregates` values: `op` ∈ `count|sum|avg|min|max|stddev|quantiles` ·
 
 ### Call 2: GetProductCatalogData
 
+**Endpoint:** `POST https://manage.wix.com/recommendations/v1/recommendations/get-product-catalog-data-tool`
+
 ```
-CallWixSiteAPI(
-  url: "https://manage.wix.com/recommendations/v1/recommendations/get-product-catalog-data-tool",
-  method: "POST",
-  body: {
-    "businessGoal": "<goal from Step 4>",
-    "minMarginPct": 0.15,
-    "catalogLimit": 30,
-    "query": "<keywords from merchant request, or empty string>",
-    "categoryNames": <category names if mentioned, or empty array>
-  }
-)
+{
+  "businessGoal": "<goal from Step 4>",
+  "minMarginPct": 0.15,
+  "catalogLimit": 30,
+  "query": "<keywords from merchant request, or empty string>",
+  "categoryNames": <category names if mentioned, or empty array>
+}
 ```
 
 **Sort order applied server-side by `businessGoal`:**
@@ -331,12 +331,10 @@ CallWixSiteAPI(
 
 **Send only categories you plan to target — max 10 per call.**
 
-```
-CallWixSiteAPI(
-  url: "https://manage.wix.com/recommendations/v1/recommendations/get-category-ids-tool",
-  method: "POST",
-  body: { "categoryNames": ["<top category 1>", "<top category 2>"] }
-)
+**Endpoint:** `POST https://manage.wix.com/recommendations/v1/recommendations/get-category-ids-tool`
+
+```json
+{ "categoryNames": ["<top category 1>", "<top category 2>"] }
 ```
 
 **Response:** `{ "categoryIds": ["a1b2c3d4-...", "b2c3d4e5-..."] }`
@@ -415,6 +413,10 @@ Analyze the site's shipping configuration using the rules below. All shipping re
 
 **Priority order:** CRITICAL blockers (no options, no coverage) → Conversion-linked (no free shipping, high rates) → Revenue opportunities (international, tiered pricing) → Configuration improvements (consolidate, add estimates).
 
+### Gift card recommendations (if GIFT_CARDS domain active)
+
+[Goal: Sell Gift Cards](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-sell-gift-cards) owns this domain end to end — the existing-product gate, denomination sizing, expiry policy, and at most one gift-card recommendation. Action type: `create_gift_card_product`.
+
 ### Cross-domain balance
 
 - If request is generic, aim for recommendations from **multiple domains** (e.g., 2-3 discount + 1-2 shipping)
@@ -435,6 +437,7 @@ Analyze the site's shipping configuration using the rules below. All shipping re
 8. **Rounding**: Discount percentages round to 5/10/15/20/25% unless merchant specified exact value.
 9. **Data-backed**: Every recommendation must reference specific data from API responses.
 10. **Domain labeled**: Every recommendation has the correct `domain` field.
+11. **Persisted**: Step 8 has run and every recommendation has an `id` from `BatchCreate`. **If you cannot point at that `id`, you are not finished — go do Step 8 now.** The only exceptions are `SKIP_TRACKING` or a `BatchCreate` call that failed, and a failure must be reported to the merchant, not passed over in silence.
 
 ---
 
@@ -442,36 +445,30 @@ Analyze the site's shipping configuration using the rules below. All shipping re
 
 **MANDATORY — do NOT skip unless the user said `SKIP_TRACKING`.**
 
-Before calling BatchCreate, load the tracking recipe to get the exact request body shape:
+Before calling BatchCreate, read the full article for the tracking recipe to get the exact request body shape:
+[API: Recommendation Tracking](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-recommendation-tracking)
 
-```
-ReadFullDocsArticle("https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-recommendation-tracking")
-```
+Then call BatchCreate to persist ALL recommendations as PROPOSED.
 
-Then call `BatchCreate` to persist ALL recommendations as PROPOSED:
+**Endpoint:** `POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/batch-create`
 
 ```
-CallWixSiteAPI(
-  url: "https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/batch-create",
-  method: "POST",
-
-  body: {
-    "agenticRecommendations": [
-      {
-        "title": "<recommendation title>",
-        "reasoning": "<recommendation reasoning>",
-        "domain": "<discounts|shipping>",
-        "urgency": "<CRITICAL|HIGH|MEDIUM|LOW>",
-        "advice": {
-          "action": "<action type>",
-          "params": <params object>,
-          "successCriteria": "<how to verify success>"
-        }
+{
+  "agenticRecommendations": [
+    {
+      "title": "<recommendation title>",
+      "reasoning": "<recommendation reasoning>",
+      "domain": "<discounts|shipping>",
+      "urgency": "<CRITICAL|HIGH|MEDIUM|LOW>",
+      "advice": {
+        "action": "<action type>",
+        "params": <params object>,
+        "successCriteria": "<how to verify success>"
       }
-    ],
-    "conversationId": "<conversationId>"
-  }
-)
+    }
+  ],
+  "conversationId": "<conversationId>"
+}
 ```
 
 **Save the `id` and `revision` from each result.** Include them in the output.
@@ -513,7 +510,7 @@ If BatchCreate fails, report the error and include recommendations without track
             "endDate": "2026-05-26"
           }
         },
-        "success_criteria": "15% discount applied site-wide for orders above $250 during Memorial Weekend"
+        "successCriteria": "15% discount applied site-wide for orders above $250 during Memorial Weekend"
       }
     }
   ]
@@ -524,17 +521,17 @@ If BatchCreate fails, report the error and include recommendations without track
 
 | Field | Rule |
 |---|---|
-| `id` | GUID from tracking BatchCreate response (omit if tracking skipped/failed) |
+| `id` | GUID from the tracking `BatchCreate` response. **Required** — an output with no `id` means Step 8 never ran, which is a failed run. Omit only when the merchant said `SKIP_TRACKING`, or when `BatchCreate` failed and you say so explicitly. |
 | `title` | Short, actionable. Max 200 chars. Always English. |
 | `reasoning` | **Must reference which API call returned the data.** Always English. |
-| `domain` | `"discounts"` or `"shipping"` (future: `"gift_cards"`, `"taxes"`) |
+| `domain` | `"discounts"`, `"shipping"`, or `"gift_cards"` (future: `"taxes"`) |
 | `urgency` | `CRITICAL`, `HIGH`, `MEDIUM`, or `LOW` |
 | `mechanism` | `AUTOMATIC` or `COUPON`. From Step 4c. Only for discounts domain. |
 | `name` | Marketing headline, 2-5 words. Translate to site `language` if not English. |
 | `why` | 1-2 sentences with specific data points from API responses. Translate to site `language`. |
 | `code` | Only for COUPON mechanism. Memorable code, max 20 chars (e.g., "SAVE15"). |
 | `scope` + IDs | For discounts: SITE = both empty, CATEGORY = categoryIds only (max 3), ITEMS = productIds only (max 5). |
-| `success_criteria` | How to verify the recommendation was applied correctly |
+| `successCriteria` | How to verify the recommendation was applied correctly |
 
 ### Valid action types by domain
 
@@ -542,6 +539,7 @@ If BatchCreate fails, report the error and include recommendations without track
 |---|---|
 | discounts | `apply_discount` |
 | shipping | `create_shipping_option`, `update_shipping_option`, `enable_backup_rate`, `activate_region` |
+| gift_cards | `create_gift_card_product` |
 
 ---