@wix/agent-skills 1.12.0 → 1.13.0

package/skills/wix-manage/references/sites/query-sites.md

@@ -1,37 +1,43 @@
 ---
 name: "Query Sites"
-description: Lists and queries all sites associated with a Wix account using Sites API. Covers pagination with cursor-based navigation.
+description: Lists and queries all sites associated with a Wix account using the Sites API. Covers filtering, sorting, and cursor-based pagination.
 ---
 # Query Sites
 
-This recipe demonstrates how to list and query all sites associated with a Wix account.
+This recipe demonstrates how to list and query the sites associated with a Wix account.
 
 ## Prerequisites
 
-- Account-level API access
-- Authorization for site listing permissions
+- Account-level API access (authenticated as a Wix user or using an account-level API key)
+- Permission `SITE_LIST.READ` (scope `SCOPE.ACC-DC-OS.READ-SITE`)
 
 ## Required APIs
 
 - **Query Sites API**: [REST](https://dev.wix.com/docs/api-reference/account-level/sites/sites/query-sites)
 
+> Returns up to **100** sites per request. Use cursor paging (below) to retrieve more.
+
 ---
 
-## Query All Sites
+## Query Sites
 
 **Endpoint**: `POST https://www.wixapis.com/site-list/v2/sites/query`
 
+The request takes a `query` object that supports `filter`, `sort`, and `cursorPaging`.
+
 **Request Body**:
 ```json
 {
   "query": {
-    "cursorPaging": {
-      "limit": 50
-    }
+    "filter": { "editorType": "EDITOR" },
+    "sort": [{ "fieldName": "createdDate", "order": "ASC" }],
+    "cursorPaging": { "limit": 50 }
   }
 }
 ```
 
+All three fields are optional — `{ "query": { "cursorPaging": { "limit": 50 } } }` lists every site.
+
 **Request**:
 ```bash
 curl -X POST \
@@ -40,9 +46,9 @@ curl -X POST \
   -H 'Content-Type: application/json' \
   -d '{
     "query": {
-      "cursorPaging": {
-        "limit": 50
-      }
+      "filter": { "editorType": "EDITOR" },
+      "sort": [{ "fieldName": "createdDate", "order": "ASC" }],
+      "cursorPaging": { "limit": 50 }
     }
   }'
 ```
@@ -51,75 +57,141 @@ curl -X POST \
 
 ## Response Structure
 
+The response has the sites array plus **two** paging objects: a top-level `cursorPaging`
+(echoes the applied limit and the next cursor) and `metadata` (count, `cursors.next`, `hasNext`).
+
+> ⚠️ There is **no** `pagingMetadata` field. Read paging info from `metadata`.
+
 ```json
 {
   "sites": [
     {
-      "id": "site-id-123",
-      "name": "My Website",
-      "displayName": "My Website",
-      "siteUrl": "https://username.wixsite.com/mywebsite",
+      "id": "f6061c5f-6aa3-42f8-8822-36a4981dabb2",
+      "htmlAppId": "70df538d-906c-44ca-9f27-c186b62f2b2b",
+      "name": "my-site-47",
+      "displayName": "My Site 47",
+      "createdDate": "2023-02-01T14:56:09.831Z",
+      "updatedDate": "2026-06-22T03:55:49.031Z",
       "published": true,
-      "createdDate": "2024-01-15T10:30:00Z",
-      "updatedDate": "2024-06-20T14:45:00Z"
+      "premium": false,
+      "viewUrl": "https://username.wixsite.com/my-site-47",
+      "editUrl": "/editor/f6061c5f-6aa3-42f8-8822-36a4981dabb2?editorSessionId=...",
+      "thumbnail": "/site-thumbnail/f6061c5f-6aa3-42f8-8822-36a4981dabb2",
+      "ownerAccountId": "e6a89eda-d100-4b2d-8a47-3040e2134497",
+      "contributorAccountIds": [],
+      "editorType": "EDITOR",
+      "blocked": false,
+      "namespace": "WIX",
+      "domainConnected": false,
+      "parentChildRole": "NONE"
     }
   ],
-  "pagingMetadata": {
+  "cursorPaging": {
+    "limit": 50,
+    "cursor": "<cursor-for-next-page>"
+  },
+  "metadata": {
     "count": 50,
     "cursors": {
-      "next": "cursor-for-next-page"
+      "next": "<cursor-for-next-page>"
     },
     "hasNext": true
   }
 }
 ```
 
+### Site object fields
+
+Each entry in `sites` has these fields (from the `Site` schema):
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | string | Site ID — use for site-level API calls |
+| `htmlAppId` | string | Internal HTML app ID |
+| `name` | string | URL slug / internal name |
+| `displayName` | string | Human-readable site name |
+| `createdDate` / `updatedDate` | datetime | |
+| `trashedDate` | datetime | Present only if the site is in the trash |
+| `published` | boolean | Whether the site is published |
+| `premium` | boolean | Whether the site has a Wix Premium (paid) plan |
+| `viewUrl` | string | Public site address; empty string when unpublished. **There is no `siteUrl` field.** |
+| `editUrl` | string | Relative editor path; prefix with `https://manage.wix.com` to open |
+| `thumbnail` | string | Relative thumbnail path |
+| `ownerAccountId` | string | |
+| `contributorAccountIds` | string[] | |
+| `editorType` | string | e.g. `EDITOR`, `ODEDITOR` — also a valid `filter` field |
+| `blocked` | boolean | |
+| `folderId` / `parentId` | string | Set for sites organized in folders / parent-child setups |
+| `namespace` | string | e.g. `WIX` |
+| `domainConnected` | boolean | |
+| `parentChildRole` | string | e.g. `NONE` |
+
 ---
 
 ## Pagination
 
-For accounts with many sites, use cursor-based pagination:
+Cursor-based. Read the next cursor from `metadata.cursors.next` and stop when
+`metadata.hasNext` is `false`.
+
+> The cursor does **not** carry the page limit, and it already encodes the filter/sort
+> from the first request. On follow-up pages send **only** the cursor (plus `limit` if you
+> want a non-default page size) — do **not** repeat `filter` or `sort`.
 
-**First Request**:
+**First request**:
 ```json
 {
   "query": {
-    "cursorPaging": {
-      "limit": 50
-    }
+    "filter": { "editorType": "EDITOR" },
+    "sort": [{ "fieldName": "createdDate", "order": "ASC" }],
+    "cursorPaging": { "limit": 50 }
   }
 }
 ```
 
-**Next Page** (using cursor from response):
+**Next page** (cursor from `metadata.cursors.next`):
 ```json
 {
   "query": {
     "cursorPaging": {
       "limit": 50,
-      "cursor": "<cursor-from-previous-response>"
+      "cursor": "<metadata.cursors.next from previous response>"
     }
   }
 }
 ```
 
-Continue until `hasNext` is `false`.
+**Loop**:
+```javascript
+async function listAllSites() {
+  const sites = [];
+  let cursor = null;
+  do {
+    const cursorPaging = cursor ? { limit: 100, cursor } : { limit: 100 };
+    const res = await wixRequest({ query: { cursorPaging } }); // POST .../site-list/v2/sites/query
+    sites.push(...res.sites);
+    cursor = res.metadata.hasNext ? res.metadata.cursors.next : null;
+  } while (cursor);
+  return sites;
+}
+```
 
 ---
 
 ## Common Use Cases
 
-### List All Sites
-Retrieve all sites without filtering - useful for account dashboards or site selection interfaces.
+### List all sites
+Omit `filter` and page through with `cursorPaging` until `metadata.hasNext` is `false`.
 
-### Find a Specific Site
-After querying, filter results by name or ID to locate a specific site.
+### Find a specific site
+Prefer server-side `filter` (e.g. `{ "editorType": "EDITOR" }`) and `sort` over fetching
+everything and filtering client-side. Filterable fields match the site object (e.g. `name`,
+`displayName`, `editorType`, `published`).
 
 ---
 
 ## Next Steps
 
 After finding a site:
-- Use the site ID for site-level API calls
+- Use the site `id` for site-level API calls
 - Create new sites using [Create Site from Template](create-site-from-template.md)
 - Manage site settings and content

package/skills/wix-manage/references/ecommerce/goal-reduce-cart-abandonment.md

@@ -1,147 +0,0 @@
----
-name: "Goal: Reduce Cart Abandonment"
-description: Maps cart abandonment reduction to recovery automation KPIs. Covers abandoned cart email automation activation, missing sales detection, and eligibility thresholds. Also references shipping flows that affect checkout drop-off.
-layer: goal
-references:
-  - name: "Flow: Fix Coverage Gaps"
-    path: ecommerce/flow-fix-coverage-gaps.md
-    load: false
-  - name: "Recipe: Apply Shipping Recommendations"
-    path: ecommerce/recipe-apply-shipping-recommendations.md
-    load: false
-  - name: "Setup Store Pickup Location"
-    path: ecommerce/setup-store-pickup-location.md
-    load: false
----
-# Goal: Reduce Cart Abandonment
-
-> **Related skills**:
-> - [Flow: Fix Coverage Gaps](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-fix-coverage-gaps) — shipping coverage gaps block checkout entirely
-> - [Recipe: Apply Shipping Recommendations](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/recipe-apply-shipping-recommendations)
-> - [Setup Store Pickup Location](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-store-pickup-location)
-
-Reduce checkout abandonment caused by shipping friction — coverage gaps, unexpected costs, and missing free shipping options — by optimizing the delivery step of the checkout funnel.
-
----
-
-## Business Goal
-
-The merchant wants to reduce the percentage of customers who abandon checkout, specifically at the delivery/shipping step. Shipping-related friction is the leading cause of checkout abandonment, and the delivery step conversion rate (delivery_step_cvr) is the primary metric.
-
-**Benchmark:** A healthy delivery_step_cvr is approximately 65%. Stores below this benchmark have significant shipping-related friction.
-
----
-
-## KPIs
-
-| KPI | Definition | How to measure | Benchmark |
-|---|---|---|---|
-| Delivery step CVR | Customers completing delivery step / customers reaching delivery step | Site metrics: delivery_step_cvr | 65% |
-| Cart abandonment rate | Carts created but not converted to orders / total carts | 1 - (orders / carts) | Industry avg ~70% |
-| Free shipping qualification rate | Orders qualifying for free shipping / total orders | Track orders meeting free shipping threshold | Higher is better |
-| Revenue from recovered checkouts | Incremental revenue from improved conversion | (new_cvr - old_cvr) * checkout_sessions * AOV | - |
-
----
-
-## Triggers
-
-Activate this goal when the merchant expresses any of the following intents:
-
-- "cart abandonment"
-- "checkout drop-off"
-- "shipping friction"
-- "delivery step"
-- "people are leaving at checkout"
-- "customers not completing orders"
-- "why are customers abandoning"
-- "checkout conversion"
-- Any request about reducing drop-off during the purchase flow
-
----
-
-## Diagnostic Questions
-
-Before recommending actions, assess the root cause of abandonment. Ask or investigate:
-
-1. **Where are buyers dropping off?** — Is it specifically the delivery step, or payment, or earlier in the funnel?
-2. **Are shipping costs visible before checkout?** — Surprise shipping costs are the #1 abandonment driver.
-3. **Is there a free shipping option?** — Free shipping (even with a threshold) dramatically reduces abandonment.
-4. **Are there shipping coverage gaps?** — Customers in unserved regions cannot complete checkout at all.
-5. **Are shipping rates reasonable?** — Rates above 10-15% of order value cause sticker shock.
-6. **Are payment methods adequate?** — Missing payment options can look like shipping-step abandonment in metrics.
-7. **Are recovery emails enabled?** — Abandoned cart emails can recapture 5-15% of abandoned carts.
-
----
-
-## Recommended Actions (Prioritized)
-
-Actions are ordered by impact. Address blocking issues first, then conversion drivers, then optimization.
-
-### Priority 1: Flow: Fix Shipping Coverage Gaps (Blocking)
-
-Coverage gaps are the most critical issue — if a customer's region is not covered by any shipping option, they literally cannot complete checkout.
-
-**When to use:** When delivery profiles show regions without active shipping options, inactive regions, or missing domestic coverage.
-
-**Impact:** Removes a hard blocker. Customers in uncovered regions have 0% conversion.
-
-### Priority 2: Flow: Add Free Shipping (Conversion Driver)
-
-Free shipping is the single most effective lever for reducing cart abandonment. Even with a minimum order threshold, offering a free shipping option significantly improves delivery step conversion.
-
-**When to use:** When the store has no free shipping option, or when the existing free shipping threshold is set too high relative to AOV.
-
-**Impact:** Typically improves delivery_step_cvr by 10-20 percentage points. The threshold should be calibrated to AOV (typically 1.2x-1.5x AOV).
-
-### Priority 3: Flow: Optimize Shipping Rates (Sticker Shock Reduction)
-
-High shipping rates cause sticker shock even when coverage exists. Rate optimization ensures pricing is competitive and proportional to order value.
-
-**When to use:** When shipping rates are disproportionately high relative to product prices, or when rates lack tiered/conditional pricing.
-
-**Impact:** Reduces abandonment from price sensitivity. Most effective when combined with free shipping at a threshold.
-
----
-
-## Measurement Plan
-
-### Before optimization
-
-1. Record baseline delivery_step_cvr from site metrics
-2. Record current cart abandonment rate
-3. Identify the specific shipping configuration state:
-   - Number of active regions with shipping options
-   - Presence/absence of free shipping
-   - Average shipping rate as percentage of AOV
-
-### During optimization (weekly monitoring for 30 days)
-
-1. Track delivery_step_cvr weekly
-2. Compare week-over-week trend
-3. Monitor free shipping qualification rate (if threshold was added)
-4. Check for new coverage gaps if regions were modified
-
-### After optimization (30-day assessment)
-
-1. Calculate CVR improvement: `new_delivery_step_cvr - baseline_delivery_step_cvr`
-2. Estimate revenue recovered: `cvr_improvement * checkout_sessions * AOV`
-3. Evaluate threshold effectiveness:
-   - Free shipping qualification rate > 40% = threshold well-calibrated
-   - Free shipping qualification rate < 10% = threshold too high, consider lowering
-4. Assess whether further optimization is needed:
-   - delivery_step_cvr >= 65% = healthy, monitor quarterly
-   - delivery_step_cvr 50-65% = improving, continue optimization
-   - delivery_step_cvr < 50% = investigate non-shipping causes (payment, UX)
-
----
-
-## Decision Matrix
-
-| Scenario | Priority Action | Rationale |
-|---|---|---|
-| Regions without shipping options | Fix Coverage Gaps (P1) | Hard blocker — 0% conversion in uncovered regions |
-| No free shipping option exists | Add Free Shipping (P2) | #1 conversion driver for delivery step |
-| Free shipping exists but threshold too high | Add Free Shipping (recalibrate) | Lower threshold to match AOV |
-| High shipping rates, free shipping exists | Optimize Shipping Rates (P3) | Reduce sticker shock for below-threshold orders |
-| delivery_step_cvr >= 65% | No immediate action needed | Already at healthy benchmark |
-| Abandonment not at delivery step | Investigate other causes | Payment methods, UX, trust signals may be the issue |

package/skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md

@@ -1,118 +0,0 @@
----
-name: "Guardrail: Discount Conflicts"
-description: Validation rules for detecting and preventing discount stacking conflicts, coupon overlap, and unintended deep discounts before applying new promotions. Covers automatic discount rules, coupon interactions, and safe discount limits.
-layer: guardrail
-references:
-  - name: "Troubleshoot: Discount Not Applying"
-    path: ecommerce/troubleshoot-discount-not-applying.md
-    load: false
----
-# Guardrail: Discount Conflicts
-
-> **Related skills** (read with `ReadFullDocsArticle` if needed):
-> - [Troubleshoot: Discount Not Applying](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/troubleshoot-discount-not-applying)
-
-## When to use this guardrail
-
-Run these checks **before** creating or updating any discount — whether automatic discount rule or coupon. Discount conflicts are one of the most common merchant mistakes — overlapping discounts silently stack and give customers a much deeper discount than intended. This is especially dangerous when **automatic discounts and coupons interact**, since merchants often forget that both mechanisms apply simultaneously.
-
----
-
-## Check 1: Existing active discount rules on the same scope
-
-**Why:** Wix eCommerce stacks automatic discount rules. If a 20% catalog-wide discount and a 15% collection discount both apply to the same product, the customer may get both applied.
-
-**How to check:**
-
-1. Query all active discount rules:
-
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query`
-
-**Request**:
-```json
-{
-  "query": {
-    "filter": {
-      "active": true
-    },
-    "paging": {
-      "limit": 100
-    }
-  }
-}
-```
-
-2. For each existing active rule, compare its scope against the new rule:
-   - If both target `CATALOG` scope: **conflict** — both apply to all products
-   - If new rule targets `CATALOG` and existing targets `COLLECTION`: **conflict** — catalog-wide includes that collection
-   - If both target the same `COLLECTION` ID: **conflict** — same products affected
-   - If both target the same `SPECIFIC_PRODUCTS` ID: **conflict** — same product
-
-3. If a conflict is found, warn the merchant:
-   > "There's already an active discount '{existingRuleName}' ({existingDiscount}%) that applies to the same products. Adding this new {newDiscount}% discount may stack, giving customers a combined discount. Would you like to deactivate the existing rule first, or proceed with both?"
-
----
-
-## Check 2: Discount percentage sanity
-
-**Why:** A discount above 50% is unusual and may indicate a typo (the merchant meant 15% not 50%). A discount of 100% makes the product free.
-
-**Rules:**
-- Discount > 50%: Warn — "This discount is {percentage}% off. Are you sure? This means a $100 product would sell for ${100 - percentage}."
-- Discount = 100%: Block unless explicitly confirmed — "This would make the product free. Please confirm this is intentional."
-- Discount > 100%: Block — "A discount cannot exceed 100%."
-
----
-
-## Check 3: Time overlap with existing promotions
-
-**Why:** Two promotions running simultaneously on overlapping products cause stacking during the overlap period.
-
-**How to check:**
-
-1. For the new rule's `activeTimeInfo` (start/end), check if any existing active rule has an overlapping time window on the same scope.
-2. Overlap exists when: `existingStart < newEnd AND existingEnd > newStart`
-3. If overlap found on the same scope: warn the merchant about the overlap period.
-
----
-
-## Check 4: Cross-mechanism stacking (Automatic + Coupon)
-
-**Why:** Automatic discounts and coupons stack with each other at checkout. A customer with a 20% coupon buying during a 20% automatic sale gets both applied — the effective discount is much deeper than either one alone. This is the most commonly overlooked stacking issue.
-
-**How to check:**
-
-1. If you are creating an **automatic discount**: Query active coupons that target overlapping products/collections.
-2. If you are creating a **coupon**: Query active automatic discount rules that target overlapping products/collections.
-3. If overlap found, warn the merchant with the combined impact:
-   > "You have an active {automatic discount / coupon} '{name}' ({X}% off) that applies to the same products. If you create this {coupon / automatic discount}, customers will get BOTH discounts — a combined effective discount of approximately {combined}%. Is this intentional?"
-
-**Key rule:** Only one coupon can be used per checkout, but automatic discounts have no such limit. The worst case is: multiple automatic discounts + one coupon all stacking on the same product.
-
----
-
-## Check 5: Minimum profit margin
-
-**Why:** Deep discounts on low-margin products can result in selling at a loss.
-
-**Rules:**
-- If the merchant has provided cost/margin information, verify that the discount doesn't reduce the price below cost
-- If no cost information is available, warn for discounts > 40% as a general safety threshold
-
----
-
-## Summary: Decision matrix
-
-| Scenario | Action |
-|---|---|
-| No conflicts found | Proceed with creating the discount |
-| Scope overlap with existing active automatic discount | Warn merchant, ask to deactivate existing or confirm stacking |
-| Cross-mechanism stacking (automatic + coupon on same scope) | Warn merchant with combined effective discount percentage |
-| Discount > 50% | Warn merchant, ask for confirmation |
-| Discount = 100% | Block unless explicitly confirmed |
-| Time overlap on same scope | Warn about overlap period |
-
-## References
-
-- [Discount Rules API (Automatic Discounts)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/introduction)
-- [Coupons API](https://dev.wix.com/docs/api-reference/business-solutions/coupons/coupons/introduction)

package/skills/wix-manage/references/ecommerce/guardrail-margin-protection.md

@@ -1,88 +0,0 @@
----
-name: "Guardrail: Margin Protection"
-description: Safety constraints for discount percentages — global discount cap, minimum margin requirements, user override protocol, and percentage sanity checks.
-layer: guardrail
----
-# Guardrail: Margin Protection
-
-## When to apply
-
-Run before EVERY discount rule creation or update. Check both the new rule's discount AND the cumulative effect with existing active rules (stacking).
-
----
-
-## Constraint 1: Global discount cap
-
-The default maximum discount percentage (`discountMargin`) is **25%**.
-
-Any discount rule that exceeds this cap should be flagged before creation:
-
-> "This discount ({pct}%) exceeds the default cap of 25%. Proceeding only because you explicitly requested it."
-
-Respect the cap unless user input explicitly overrides it.
-
----
-
-## Constraint 2: Minimum margin requirement
-
-The default minimum margin percentage (`minMarginPct`) is **15%**.
-
-Never create a discount that would push the effective margin below 15% unless the user explicitly overrides this constraint.
-
-If cost data is available, calculate:
-- `effective_margin = (price - cost - discount_amount) / price × 100`
-- If `effective_margin < minMarginPct` → block and explain the margin impact.
-
----
-
-## Constraint 3: Percentage sanity checks
-
-| Discount value | Action |
-|---|---|
-| Discount > 50% | Warn — "This discount is {pct}% off. A $100 product would sell for ${100 - pct}. Are you sure?" |
-| Discount = 100% | Block unless explicitly confirmed — "This makes the product free." |
-| Discount > 100% | Block always — "A discount cannot exceed 100%." |
-
----
-
-## Constraint 4: User input override protocol (ABSOLUTE PRIORITY)
-
-User input overrides ALL constraints — margin caps, discount caps, naming conventions, percentage limits.
-
-**How it works:**
-
-- If the user says "50% discount" and the cap is 25%, honor 50%.
-- If the user says "set margin to 5%" and the minimum is 15%, honor 5%.
-- Document which constraints were overridden in reasoning so there is a clear audit trail.
-
-**Example reasoning output:**
-
-> "Creating a 50% discount as requested. Note: this overrides the default 25% discount cap. The effective margin on a product with 60% gross margin would drop to 10%, below the default 15% minimum margin threshold. Proceeding per explicit user instruction."
-
----
-
-## Constraint 5: Stacking cumulative check
-
-When creating a new discount, also check the cumulative effect with existing active rules:
-
-1. Query all active discount rules that overlap in scope with the new rule.
-2. Calculate the combined discount percentage (accounting for multiplicative stacking).
-3. If the combined discount exceeds the global cap or violates the minimum margin, warn the merchant:
-
-> "Combined with the existing '{existingRuleName}' ({existingPct}%), the total effective discount would be approximately {combinedPct}%. This exceeds the {cap}% cap / pushes margin below {minMarginPct}%."
-
----
-
-## Summary: Decision matrix
-
-| Scenario | Action |
-|---|---|
-| Discount ≤ 25% and margin ≥ 15% | Proceed |
-| Discount > 25% but ≤ 50%, no user override | Warn, ask for confirmation |
-| Discount > 25%, user explicitly requested | Proceed, document override |
-| Discount > 50% | Warn with dollar example, ask for confirmation |
-| Discount = 100% | Block unless explicitly confirmed |
-| Discount > 100% | Block always |
-| Combined stacking exceeds cap | Warn about cumulative effect |
-| Margin drops below 15%, no user override | Block, explain margin impact |
-| Margin drops below 15%, user override | Proceed, document override |