/wix-manage

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 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 read
Holiday / event / date mentioned	Goal: Seasonal Revenue
"increase AOV", "spend more", "upsell", "boost sales", generic sales improvement	Goal: Increase AOV
"clear inventory", "overstock", "clearance", "slow-moving"	Goal: Clear Inventory
"bundle", "cross-sell", "buy together", "more items per order"	Goal: Drive Cross-Sells
"sell gift cards", "add a gift card", "gift card amounts / denominations"	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.

If COUPON mechanism in Step 4c, also load:

• Pricing: Create Coupon

EXECUTION RULES — READ BEFORE ANYTHING ELSE

You are an operator, not a consultant. When this recipe is activated:

1. Do NOT ask clarifying questions — start executing immediately from Step 1. The merchant's request contains enough information. The analysis steps will determine which domains and strategies apply.
2. Do NOT produce recommendations before calling the mandatory APIs. If you skip the API calls and generate advice from assumptions, your output is wrong — even if it sounds reasonable.
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. 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.

Step 1: Resolve the target site

MANDATORY — do this first.

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.

Do not proceed without a siteId.

Step 2: Load recommendation history (Tracking)

MANDATORY — do NOT skip unless the user said SKIP_TRACKING or "don't track".

Query the tracking database for existing recommendations on this site.

Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/query

{ "query": { "filter": {}, "cursorPaging": { "limit": 50 } } }

Use the returned history to inform your analysis:

If the query returns empty results or fails, continue — this is a fresh session.

Step 3: Gather site data

MANDATORY API CALL — do not skip.

Endpoint: POST https://www.wix.com/wix-profile-client/v4/profile/metasite

{
  "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:

Response shape — each field is a nested object; missing fields = no data for this site:

{
  "metaSiteId": "<msid>",
  "fields": {
    "language":                    { "aSingleValue": { "aString": "en-US" } },
    "merchant_business_country":   { "aSingleValue": { "aString": "US" } },
    "payment_currency":            { "aSingleValue": { "aString": "USD" } },
    "last_30_days_orders_count":   { "aSingleValue": { "aLong": "2141" } },
    "online_gpv_last_30_days":     { "aSingleValue": { "aLong": "526550" } }
  }
}

Extracting values:

• String: fields.<name>.aSingleValue.aString
• Number: fields.<name>.aSingleValue.aLong — returned as a JSON string, parse to int before arithmetic

Derived value: aov = parseInt(online_gpv_last_30_days) / parseInt(last_30_days_orders_count) — in payment_currency units

Currency rule: All monetary values (online_gpv_last_30_days, aov, discount thresholds, shipping amounts) are in the site's payment_currency. Never assume USD. Always display and compute amounts using payment_currency.

STOP if merchant_business_country, suggested_main_industry, or online_gpv_last_30_days are missing or null. Report: "Cannot generate recommendations — missing required site data: {fields}."

Step 3b: Validate the request

Check if the merchant's request includes anything unsupported. Reject these:

If valid, continue.

Step 4: Identify applicable domains

Based on the merchant's request AND the site data, determine which domains to analyze. Multiple domains can be active simultaneously.

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.

If the request is generic (e.g., "boost my sales", "help my business"), activate ALL domains. The best recommendations will come from analyzing every angle.

If the request targets a specific domain (e.g., "give me a coupon", "fix my shipping rates", "set up a gift card"), activate ONLY that domain. Do not generate cross-domain recommendations — focus all 5 recommendation slots on the requested domain. The merchant asked for something specific; respect that focus.

Step 4b: Load domain-specific goal skills

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:

For GIFT_CARDS domain — load 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.

Do NOT skip this step. The goal/flow/guardrail skills contain critical constraints (margin tiers, campaign windows, conflict checks) that prevent bad recommendations.

Step 4c: Determine mechanism — Automatic Discount or Coupon

Only for DISCOUNTS domain. Skip if DISCOUNTS is not active.

If unclear, ask: "Would you like this to apply automatically to everyone, or as a coupon code?"

If COUPON is selected, read the full article for the coupon setup reference: Pricing: Create Coupon

Step 5: Analyze catalog

Permission: ecom:discounts_recommendations:v1:recommendation:build_recommendation

Call both APIs concurrently:

Call 1: GetCatalogAnalytics

Endpoint: POST https://manage.wix.com/recommendations/v1/recommendations/get-catalog-analytics-tool

{
  "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)

Aggregates by goal:

Response shape:

{
  "categoryGroups": [
    {
      "categoryName": "Electronics",
      "fields": {
        "count()": 45,
        "quantiles([0.5,0.75,0.9],price)": [
          { "quantile": 0.5, "value": 89.99 },
          { "quantile": 0.75, "value": 149.99 }
        ],
        "avg(profitMargin)": 0.42
      }
    },
    { "categoryName": "All Products", "fields": { "count()": 120, "avg(profitMargin)": 0.35 } }
  ]
}

Important: Use "All Products" only for overall catalog stats. Exclude it from category-level analysis.

Call 2: GetProductCatalogData

Endpoint: POST https://manage.wix.com/recommendations/v1/recommendations/get-product-catalog-data-tool

{
  "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:

Response shape:

{
  "items": [
    {
      "id": "product-uuid",
      "name": "Premium Headphones",
      "quantity": 85,
      "price": 149.99,
      "profit": 67.50,
      "profitMargin": 0.45,
      "ordersCount": 23
    }
  ]
}

price and profit are in payment_currency units. id is the product UUID — use for productIds in rules.

Step 5b: Convert category names to GUIDs (if using CATEGORY scope)

MANDATORY before outputting any categoryIds. Never output category names as IDs.

Send only categories you plan to target — max 10 per call.

Endpoint: POST https://manage.wix.com/recommendations/v1/recommendations/get-category-ids-tool

{ "categoryNames": ["<top category 1>", "<top category 2>"] }

Response: { "categoryIds": ["a1b2c3d4-...", "b2c3d4e5-..."] }

If categoryIds is empty: category doesn't exist — fall back to SITE scope and tell the merchant: "Could not resolve category '{name}', using site-wide scope instead."

Failure handling

• Both calls fail: Fall back to SITE scope using only site profile data.
• One fails: Use whichever succeeded.

Step 6: Generate recommendations across ALL active domains

Only now — after data gathering — generate recommendations.

Maximum 5 recommendations total across all domains. Each recommendation includes its domain field.

Discount recommendations (if DISCOUNTS domain active)

Use site data + catalog data to generate discount recommendations. Each should use a different strategy:

Scope selection (in order of preference):

1. CATEGORY (preferred): High-opportunity category from analytics. Must have GUID from GetCategoryIds.
2. ITEMS (specific): Individual products from catalog data. Max 5 product IDs.
3. SITE (fallback): When no clear category/product opportunity.

Performance signals:

Discount constraints:

• Discount must not exceed discountMargin from site data (unless merchant overrides)
• Round percentages to 5/10/15/20/25% unless merchant specified exact value
• All categoryIds must be GUIDs from GetCategoryIds
• All productIds must be from GetProductCatalogData
• Mechanism must be AUTOMATIC or COUPON per Step 4c

Shipping recommendations (if SHIPPING domain active)

Analyze the site's shipping configuration using the rules below. All shipping recommendations use domain: "shipping".

Externally managed regions: Regions where deliveryCarriers[].appId matches an external carrier (e.g., Shippo) — exclude from ALL analysis. Do not recommend changes to these.

Shipping analysis rules — evaluate each and recommend where data supports:

Shipping action types: create_shipping_option, update_shipping_option, enable_backup_rate, activate_region.

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 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)
• If request targets a specific domain, focus all slots on that domain
• Rank by business impact: CRITICAL blockers first, then conversion-linked, then revenue opportunities

Step 7: Validate before returning

1. Conflict check: Do existing active discounts/coupons overlap with your recommendation scope? Warn about stacking.
2. Margin check: Discounts within discountMargin cap.
3. No duplicates: Each recommendation targets a different scope/action combination.
4. No contradictions: Don't recommend opposite actions in the same domain.
5. Strategy diversity: Discount recommendations use different strategies where possible.
6. Mechanism match: Discount mechanism matches Step 4c determination.
7. ID validity: All categoryIds are GUIDs from GetCategoryIds. All productIds are from GetProductCatalogData.
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.

Step 8: Persist recommendations to database (Tracking)

MANDATORY — do NOT skip unless the user said SKIP_TRACKING.

Before calling BatchCreate, read the full article for the tracking recipe to get the exact request body shape: API: Recommendation Tracking

Then call BatchCreate to persist ALL recommendations as PROPOSED.

Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/batch-create

{
  "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>"
}

Save the id and revision from each result. Include them in the output.

If BatchCreate fails, report the error and include recommendations without tracking IDs.

Output format

{
  "recommendations": [
    {
      "id": "<tracking-id from BatchCreate, or omit if tracking failed>",
      "revision": "<revision from BatchCreate>",
      "title": "Memorial Weekend Flash Sale — 15% Off Orders Over $250",
      "reasoning": "AOV is $242 (online_gpv_last_30_days / last_30_days_orders_count). merchant_business_country is US, Memorial Day is within 7 days. Setting $250 threshold nudges carts above AOV while staying within 25% discount cap.",
      "domain": "discounts",
      "urgency": "HIGH",
      "advice": {
        "action": "apply_discount",
        "params": {
          "mechanism": "AUTOMATIC",
          "scope": "SITE",
          "categoryIds": [],
          "productIds": [],
          "name": "Memorial Weekend Sale",
          "why": "Your AOV is $242. A 15% discount on orders over $250 encourages adding one more item.",
          "discountType": "PERCENTAGE",
          "discount": 15,
          "code": "",
          "usageLimit": 0,
          "limitPerCustomer": 0,
          "conditions": {
            "minItemQuantity": 0,
            "minSubTotal": 250,
            "startDate": "2026-05-23",
            "endDate": "2026-05-26"
          }
        },
        "successCriteria": "15% discount applied site-wide for orders above $250 during Memorial Weekend"
      }
    }
  ]
}

Field rules

Valid action types by domain

Constraints

• Maximum 5 recommendations total across all domains
• Each discount recommendation must use a different strategy
• All data must come from API responses — no assumptions
• Respect discountMargin cap unless merchant overrides
• All IDs must be GUIDs from API responses
• Catalog queries limited to 30 items
• Every recommendation MUST be persisted via tracking before presenting (unless SKIP_TRACKING)
• Recommendations should span multiple domains when the request is generic
• Never recommend changes to externally managed (Shippo) shipping regions