diff --git a/skills/wix-manage/SKILL.md b/skills/wix-manage/SKILL.md index 1507a7d9..d5e0527f 100644 --- a/skills/wix-manage/SKILL.md +++ b/skills/wix-manage/SKILL.md @@ -108,72 +108,125 @@ These recipes do NOT cover frontend development or SDK usage for displaying data ## eCommerce -**Routing — pick the right entry point:** -- **Any sales/business improvement request** (boost sales, promotions, help my business, holiday deals, improve revenue, discounts, shipping, coupons, clearance) → use [Recommend: eCommerce Strategy](references/ecommerce/recommend-ecommerce-strategy.md). This is the **default entry point** — it analyzes ALL domains (discounts, shipping, future: gift cards, taxes) and generates cross-domain recommendations. Do NOT ask clarifying questions. -- **Apply previously generated shipping recommendations** → use [Recipe: Apply Shipping Recommendations](references/ecommerce/recipe-apply-shipping-recommendations.md) -- **Store pickup configuration** → use [Setup Store Pickup Location](references/ecommerce/setup-store-pickup-location.md) -- **Discount not working at checkout** → use [Troubleshoot: Discount Not Applying](references/ecommerce/troubleshoot-discount-not-applying.md) -- **Checkout delivery step drop-off** → use [Troubleshoot: Checkout Delivery Drop-off](references/ecommerce/troubleshoot-checkout-delivery-dropoff.md) +**Routing structure** (rules + format in the `wix-skills-routing-expert` Claude Code skill — repo `ecom-ai-agents/.claude/skills/`): Each L2 category has a sibling `.md` (README-surfaced description) + a `/` folder with the dispatcher + promotion files. The migrated eCommerce L2 categories are **Tax**, **Pricing & promotions**, **Shipping**, **Checkout & cart**, **Abandoned carts**, **Fulfillment**, and **Orders**. -### [Recommend: eCommerce Strategy](references/ecommerce/recommend-ecommerce-strategy.md) -**THE entry point for all eCommerce recommendation requests.** Unified skill that analyzes site data across ALL domains (discounts + shipping), generates up to 5 cross-domain recommendations, and persists them to the tracking database. Covers discount strategies (seasonal, upsell, stock mover, bundling) AND shipping optimization (coverage gaps, free shipping, rate strategy, carrier backup). Use this for ANY business improvement request. +**L1 context loader (per L1 domain, sibling to category-docs):** -### [Recipe: Apply Shipping Recommendations](references/ecommerce/recipe-apply-shipping-recommendations.md) -**Technical:** Applies AI-generated shipping recommendations. Creates or updates shipping options based on recommendation data. +### [eCommerce: Load Context](references/ecommerce/ecom-load-context.md) +Per-L1 context loader for the eCommerce domain. Loads site profile (country, region, industry, currency, AOV, etc.) + eCommerce-specific runtime fields (tax `calculator`). Referenced from every eCommerce category's `default.md`. Skip if already loaded. -### [Setup Store Pickup Location](references/ecommerce/setup-store-pickup-location.md) -**Technical:** Configures in-store pickup at checkout using Delivery Profiles API. +When other L1 domains migrate (Stores, Get-paid, …), each gets its own `-load-context.md` at its L1 root — Stores will detect Catalog V1/V3, Get-paid will inspect payment provider state, etc. See the "Pattern for future L1 loaders" section in `ecom-load-context.md` for the convention. -### [Troubleshoot: Discount Not Applying](references/ecommerce/troubleshoot-discount-not-applying.md) -**Technical:** Diagnostic tree for inactive discounts — checks active status, time window, scope targeting, revision mismatch, app installation. +--- + +### Tax category + +#### [Tax](references/ecommerce/ecom-tax.md) +README-surfaced category-doc **and** dispatcher (merged — prototype). Disambiguates the category, then picks Avalara / EU-VAT / Wix-Manual / audit / troubleshoot / switch based on the merchant's request + MerchantContext. No separate `-default` hop. + +#### Tax promotions +- [Configure Tax (Wix Manual)](references/ecommerce/tax/ecom-tax-configure.md) — baseline manual calculator setup +- [Configure Tax (Avalara)](references/ecommerce/tax/ecom-tax-avalara.md) — context promotion `[calculator:AVALARA]` +- [Configure Tax (EU VAT)](references/ecommerce/tax/ecom-tax-eu-vat.md) — context promotion `[region:EU]` +- [Switch Tax Calculator](references/ecommerce/tax/ecom-tax-switch-calculator.md) +- [Audit Tax Setup](references/ecommerce/tax/ecom-tax-audit.md) (read-only) +- [Tax Calculation Wrong](references/ecommerce/tax/ecom-tax-troubleshoot-calc-wrong.md) (diagnostic) + +--- + +### Pricing & Promotions category + +#### [Pricing & Promotions](references/ecommerce/ecom-pricing.md) +README-surfaced category-doc **and** dispatcher (merged). Disambiguates the category, then picks the right Pricing promotion based on the merchant's intent + MerchantContext. No separate `-default` hop. -### [Troubleshoot: Checkout Delivery Drop-off](references/ecommerce/troubleshoot-checkout-delivery-dropoff.md) -**Technical:** Diagnostic tree for delivery step conversion below 65% benchmark. +#### Pricing promotions (direct merchant entry points) +- [Create Coupon](references/ecommerce/pricing-promotions/ecom-pricing-create-coupon.md) — Coupons V2 API +- [Create Discount Rule](references/ecommerce/pricing-promotions/ecom-pricing-create-discount-rule.md) — auto-apply discount rules +- [Run a Sale (orchestrator)](references/ecommerce/pricing-promotions/ecom-pricing-run-a-sale.md) — the cross-domain strategy orchestrator (formerly `recommend-ecommerce-strategy`) +- [Discount Not Applying](references/ecommerce/pricing-promotions/ecom-pricing-troubleshoot-not-applying.md) — diagnostic tree
-Internal skills (loaded automatically by the entry points above — do NOT use directly) - -#### Goals -- [Goal: Increase AOV](references/ecommerce/goal-increase-aov.md) — UPSELL_BOOST -- [Goal: Clear Inventory](references/ecommerce/goal-clear-inventory.md) — STOCK_MOVER -- [Goal: Seasonal Revenue](references/ecommerce/goal-seasonal-revenue.md) — SEASONAL -- [Goal: Drive Cross-Sells](references/ecommerce/goal-drive-cross-sells.md) — BUNDLE_AND_SAVE -- [Goal: Reduce Cart Abandonment](references/ecommerce/goal-reduce-cart-abandonment.md) — Shipping - -#### Flows -- [Flow: Upsell Boost](references/ecommerce/flow-upsell-boost.md) -- [Flow: Bundle and Save](references/ecommerce/flow-bundle-and-save.md) -- [Flow: Stock Mover](references/ecommerce/flow-stock-mover.md) -- [Flow: Seasonal Promotion](references/ecommerce/flow-seasonal-promotion.md) -- [Flow: Fix Coverage Gaps](references/ecommerce/flow-fix-coverage-gaps.md) -- [Flow: Add Free Shipping](references/ecommerce/flow-add-free-shipping.md) -- [Flow: Optimize Shipping Rates](references/ecommerce/flow-optimize-shipping-rates.md) - -#### Guardrails -- [Guardrail: Discount Conflicts](references/ecommerce/guardrail-discount-conflicts.md) -- [Guardrail: Margin Protection](references/ecommerce/guardrail-margin-protection.md) -- [Guardrail: Shipping Health](references/ecommerce/guardrail-shipping-health.md) -- [Guardrail: Rate Pricing Sanity](references/ecommerce/guardrail-rate-pricing-sanity.md) - -#### Config & API References -- [API: Recommendation Tracking](references/ecommerce/api-recommendation-tracking.md) -- [API: Shipping Delivery](references/ecommerce/api-shipping.md) -- [Setup: Discount Rules](references/ecommerce/setup-discount-rules.md) -- [Setup: Coupons](references/ecommerce/setup-coupons.md) -- [Setup: Shipping Regions](references/ecommerce/setup-shipping-regions.md) -- [Setup: Shipping Rates](references/ecommerce/setup-shipping-rates.md) - -#### Tracking -- Tracking is built into [Recommend: eCommerce Strategy](references/ecommerce/recommend-ecommerce-strategy.md) (Steps 2 + 8) — no separate skill needed -- [API: Recommendation Tracking](references/ecommerce/api-recommendation-tracking.md) — CRUD API reference for the tracking service +Pricing support files (goal-* / flow-* / guardrail-* / tracking-api) — flat in pricing-promotions/, loaded by the orchestrator, NOT direct entry points -#### Reference -- [Skill Graph](references/ecommerce/skill-graph.md) +- [Goal: Increase AOV](references/ecommerce/pricing-promotions/ecom-pricing-goal-increase-aov.md) — UPSELL_BOOST +- [Goal: Clear Inventory](references/ecommerce/pricing-promotions/ecom-pricing-goal-clear-inventory.md) — STOCK_MOVER +- [Goal: Seasonal Revenue](references/ecommerce/pricing-promotions/ecom-pricing-goal-seasonal-revenue.md) — SEASONAL +- [Goal: Drive Cross-Sells](references/ecommerce/pricing-promotions/ecom-pricing-goal-drive-cross-sells.md) — BUNDLE_AND_SAVE +- [Flow: Upsell Boost](references/ecommerce/pricing-promotions/ecom-pricing-flow-upsell-boost.md) +- [Flow: Bundle and Save](references/ecommerce/pricing-promotions/ecom-pricing-flow-bundle-and-save.md) +- [Flow: Stock Mover](references/ecommerce/pricing-promotions/ecom-pricing-flow-stock-mover.md) +- [Flow: Seasonal Promotion](references/ecommerce/pricing-promotions/ecom-pricing-flow-seasonal-promotion.md) +- [Pricing & Discount Health](references/ecommerce/pricing-promotions/ecom-pricing-health.md) — periodic conflict/stale-sale/margin sweep +- [API: Recommendation Tracking](references/ecommerce/pricing-promotions/ecom-pricing-tracking-api.md) + +(Discount-conflict & margin guardrails are inlined into Create Discount Rule / Create Coupon — the skills they guard — rather than separate files.)
--- +### Shipping category + +#### [Shipping](references/ecommerce/ecom-shipping.md) +README-surfaced category-doc **and** dispatcher (merged). Covers shipping config — rates, regions/coverage, pickup/local delivery, free-shipping thresholds, rate optimization, and wrong-rate troubleshooting. Order-fulfillment ops — mark fulfilled, tracking, labels — belong to **Fulfillment**. The Shipping Options + Delivery Profiles APIs have no public docs page, so `ecom-shipping-api.md` is the inline reference. + +#### Shipping promotions +- [Set Up Rates](references/ecommerce/shipping/ecom-shipping-setup-rates.md) +- [Set Up Regions / Coverage](references/ecommerce/shipping/ecom-shipping-setup-regions.md) +- [Set Up Pickup / Local Delivery](references/ecommerce/shipping/ecom-shipping-setup-pickup.md) +- [Add Free Shipping](references/ecommerce/shipping/ecom-shipping-free-shipping.md) +- [Optimize Rates](references/ecommerce/shipping/ecom-shipping-optimize-rates.md) +- [Fix Coverage Gaps](references/ecommerce/shipping/ecom-shipping-fix-coverage.md) + +#### Shipping support (loaded via body links, not direct entries) +- [API Reference](references/ecommerce/shipping/ecom-shipping-api.md) — inline spec (no public docs page) + +(Rate-pricing-sanity and shipping-health guardrails are inlined into their caller recipes — free-shipping / optimize-rates and fix-coverage. The generic "apply shipping recommendations" recipe was dissolved — the LLM applies recs directly via the create/update endpoints in the API Reference.) + +### Checkout & Cart category + +#### [Checkout & Cart](references/ecommerce/ecom-checkout.md) +README-surfaced category-doc **and** dispatcher (merged). Covers live checkout abandonment reduction, checkout troubleshooting, agentic readiness, and store-health. Abandoned-checkout recovery after the shopper leaves belongs to **Abandoned carts**. Most checkout *config* (guest checkout, minimum order, custom fields, upsell) is **Dashboard-only** — the dispatch routes those to the Wix Dashboard. + +#### Checkout promotions +- [Reduce Abandonment](references/ecommerce/checkout/ecom-checkout-reduce-abandonment.md) — delivery-step friction angle; also loaded by run-a-sale's ABANDONED_CART branch +- [Troubleshoot Delivery Drop-off](references/ecommerce/checkout/ecom-checkout-troubleshoot-dropoff.md) +- [Agentic Readiness](references/ecommerce/checkout/ecom-checkout-agentic-readiness.md) — catalog data-quality audit + programmatic test-checkout (AI agents) +- [Store Health Monitor](references/ecommerce/checkout/ecom-checkout-store-health.md) — periodic checkout/config-drift/anomaly checks + +### Abandoned Carts category + +#### [Abandoned Carts](references/ecommerce/ecom-abandoned-carts.md) +README-surfaced category-doc **and** dispatcher (merged). Covers abandoned-checkout recovery and recapture after the shopper leaves: viewing abandoned checkouts, recovery emails, recovery links, troubleshooting recovery, and recovery health monitoring. + +#### Abandoned Carts promotions +- [Recover Abandoned Carts via Email](references/ecommerce/abandoned-carts/ecom-abandoned-carts-recover-email.md) — Dashboard-configured automation; recipe guides timing/content/eligibility +- [Generate Recovery Link](references/ecommerce/abandoned-carts/ecom-abandoned-carts-recovery-link.md) — Abandoned Checkout API link generation +- [Troubleshoot Recovery](references/ecommerce/abandoned-carts/ecom-abandoned-carts-troubleshoot-recovery.md) +- [Recovery Health Monitor](references/ecommerce/abandoned-carts/ecom-abandoned-carts-recovery-health.md) + +### Fulfillment category + +#### [Fulfillment](references/ecommerce/ecom-fulfillment.md) +README-surfaced category-doc **and** dispatcher (merged). Covers post-purchase fulfillment operations: finding unshipped/problematic orders, marking orders fulfilled, updating tracking, partial fulfillment, bulk fulfillment, invoices/packing slips, and Dashboard-only shipping labels. + +#### Fulfillment promotions +- [Fulfill Orders & Tracking](references/ecommerce/fulfillment/ecom-fulfillment-fulfill-orders.md) — mark fulfilled, tracking, partial fulfillment +- [Bulk Fulfill Orders](references/ecommerce/fulfillment/ecom-fulfillment-bulk-fulfill-orders.md) — batch fulfillment with partial-failure handling + +### Orders category + +#### [Orders](references/ecommerce/ecom-orders.md) +README-surfaced category-doc **and** dispatcher (merged). Covers eCommerce order lookup, order details/counts, order search, pending/stuck-order diagnosis, cancel-order routing, and explicit handoffs to Fulfillment and Payments. + +#### Orders promotions +- [Cancel Order](references/ecommerce/orders/ecom-orders-cancel-order.md) — cancel order with restock/email/refund guardrails + +#### Reference +- [Skill Graph](references/ecommerce/skill-graph.md) — author docs only, NOT a runtime skill + +--- + ## Forms ### [Create Form](references/forms/create-form.md) diff --git a/skills/wix-manage/references/ecommerce/abandoned-carts/ecom-abandoned-carts-recover-email.md b/skills/wix-manage/references/ecommerce/abandoned-carts/ecom-abandoned-carts-recover-email.md new file mode 100644 index 00000000..63dbf467 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/abandoned-carts/ecom-abandoned-carts-recover-email.md @@ -0,0 +1,81 @@ +--- +name: "Abandoned Carts: Recover via Email" +description: Sets up automated abandoned-cart / abandoned-checkout recovery emails. Covers Wix Dashboard automation, send timing, email content, eligibility, recovery-rate benchmarks, and when to use API-generated recovery links instead. +--- + +# Recover Abandoned Carts via Email + +Set up an automated email that follows up with shoppers who started but did not finish checkout. This is the **email-recovery** lever. If the merchant wants to fix why shoppers leave during checkout, route to [Reduce Abandonment](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/checkout-reduce-abandonment). + +Merchants often say "abandoned carts"; the public API calls them **Abandoned Checkouts**. + +> **Where this is configured.** The recurring recovery email automation is a built-in Wix automation set up in the Dashboard. The trigger -> send path is not a verified TPA-public API. Use Analytics APIs for reporting questions. Use the Abandoned Checkout API for record-level verification, automation activity inspection, or redirecting a shopper back to checkout for custom flows. + +## API and Dashboard status + +| Capability | Route | Status | +|---|---|---| +| Configure recurring abandoned-cart email automation | Wix Dashboard -> Marketing -> Automations | Dashboard-managed | +| Measure recovery performance or abandoned-cart trends | Analytics Data API / Semantic Model API | Site Analytics read | +| Inspect specific buyer/status/activity fields | `POST https://www.wixapis.com/ecom/v1/abandoned-checkout/query` | TPA-public, drill-down | +| Redirect shopper back to checkout for a one-off custom message | `GET https://www.wixapis.com/ecom/v1/abandoned-checkout/{abandonedCheckoutId}/redirect-to-checkout?metasiteId={metasiteId}` | TPA-public | + +## Required APIs for verification only + +- `POST https://www.wixapis.com/ecom/v1/abandoned-checkout/query` — list eligible abandoned checkouts, filter by date/status/buyer, and inspect automation `activities` when available. +- `GET https://www.wixapis.com/ecom/v1/abandoned-checkout/{abandonedCheckoutId}` — verify a specific checkout before using it in a custom recovery flow. + +## Prerequisites + +- Wix Stores or another eCommerce solution is installed. +- A sender email / verified business email is connected. +- Checkout captures a customer email. Guest checkouts without an email cannot be recovered by email. + +## Step 1: Enable the abandoned-cart automation + +Direct the merchant to the built-in automation: + +> **Wix Dashboard -> Marketing -> Automations**. Find the pre-built **Recover abandoned carts** automation and turn it on. If it does not exist, create a new automation with: +> - **Trigger:** Abandoned checkout / cart (eCommerce) +> - **Action:** Send an email to the shopper + +## Step 2: Set the send timing + +| Timing | Use | Notes | +|---|---|---| +| 1 hour after abandonment | Single-email default | Catches distracted shoppers while intent is fresh | +| 1 hour + 24 hours | Higher recovery | Second nudge for price or shipping hesitation | +| +72 hours with incentive | Optional third email | Only if margins allow a small discount | + +Avoid sending more than about three emails. Beyond that, unsubscribes usually outweigh recoveries. + +## Step 3: Write the recovery email + +Include, in priority order: + +1. Cart contents, such as product image and name. +2. A clear "Complete your order" button. +3. Reassurance, such as shipping policy, return policy, or support contact. +4. Optional incentive, such as a small discount or free-shipping nudge. + +## Step 4: Eligibility and guardrails + +- **Consent:** Respect marketing opt-out flags. +- **No double-send:** Do not send recovery email for checkouts that converted. +- **Discount stacking:** If the email includes an incentive, confirm it will not stack with existing automatic discounts. +- **Email captured only:** If the checkout did not capture an email, use broader checkout optimization instead of email recovery. + +## Measurement + +- **Recovery rate** = recovered abandoned checkouts / abandoned checkouts that were eligible for recovery. +- Use Analytics APIs for recovery performance, abandonment trends, and reporting. For custom reports, discover the relevant Semantic Model fields first and do not invent a ready-made "recovery rate" field unless the analytics model exposes it. +- Use 5-15% as a rough benchmark, but do not claim any API returns a single ready-made "recovery rate" field unless it is present in the data you queried. +- Track over 30 days. If recovery is below 5%, revisit timing, subject line, cart rendering, eligibility, and whether the checkout redirect still works. + +## API-assisted path + +For a custom recovery flow, use [Generate a recovery link / resume checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/abandoned-carts-recovery-link). Prefer the Dashboard automation for recurring email sends because it handles consent, throttling, and send orchestration. + +## Audit note + +This file is not redundant with the public API docs because the public API does not configure Wix Automations. The value of this skill is the Dashboard/API boundary, timing guidance, eligibility guardrails, and when to switch to the API-assisted recovery-link recipe. diff --git a/skills/wix-manage/references/ecommerce/abandoned-carts/ecom-abandoned-carts-recovery-health.md b/skills/wix-manage/references/ecommerce/abandoned-carts/ecom-abandoned-carts-recovery-health.md new file mode 100644 index 00000000..2746ef5f --- /dev/null +++ b/skills/wix-manage/references/ecommerce/abandoned-carts/ecom-abandoned-carts-recovery-health.md @@ -0,0 +1,93 @@ +--- +name: "Abandoned Carts: Recovery Health" +description: Monitors abandoned-checkout recovery health by comparing abandoned-checkout volume, recovery rate, automation state, and common failure signals. Routes root causes to checkout, shipping, pricing, or recovery troubleshooting. +--- + +# Recovery Health Monitor + +Use this for periodic or on-demand health checks of abandoned-checkout recovery. The goal is to spot whether recovery is underperforming and identify the likely reason. + +Merchants often say "abandoned carts"; the API entity is **Abandoned Checkout**. For information, reporting, and trend questions, use Analytics APIs first. Use the Abandoned Checkout API for record-level drill-down and recovery-link verification. + +## Required APIs and inferred metrics + +| Measurement | Source | Status | +|---|---|---| +| Abandoned checkout count / trend | Analytics Data API or Semantic Model API | Site Analytics read; Semantic Model API is Developer Preview | +| Conversion/recovery performance | Semantic Model API, after discovering available measures and dimensions | Site Analytics read; do not invent field names | +| Automation activity signals | `activities` on abandoned checkout objects, when Wix Automations populated them | TPA-public read, Dashboard-configured | +| Redirect/link usability | `GET /ecom/v1/abandoned-checkout/{abandonedCheckoutId}/redirect-to-checkout?metasiteId={metasiteId}` | TPA-public | +| Record-level abandoned checkout evidence | `POST /ecom/v1/abandoned-checkout/query` or `/search` | TPA-public, drill-down only | +| Recovered count / recovery rate | Analytics model fields if available; otherwise infer from abandoned checkout status/activity plus order/recovery attribution if present | Do not claim a single guaranteed field | +| Automation enabled/configured | Wix Dashboard -> Marketing -> Automations | Dashboard-managed | + +## What to measure + +Collect enough data to answer: + +- How many abandoned checkouts happened in the period? +- How many were recovered? +- Did abandonment spike compared with a trailing baseline? +- Did recovery rate drop compared with a trailing baseline? +- Are recovery emails or links enabled and usable? + +Use this rough benchmark: + +- **Healthy:** recovery rate is stable and generally in the 5-15% range. +- **Warning:** recovery rate drops materially, abandonment spikes, or eligible abandoned checkouts are not receiving recovery. +- **Critical:** recovery links fail, automation is disabled, or checkout cannot complete. + +## Analytics checks + +For information queries such as "how many abandoned carts", "did recovery drop", or "show a report", use Analytics APIs before record lookup: + +```http +GET https://www.wixapis.com/analytics/v2/site-analytics/data +POST https://www.wixapis.com/analytics/semantic-model/v3/semantic-models/query-data +``` + +Use `analytics/v2/site-analytics/data` for available high-level site measurements. Use the Semantic Model API for custom abandoned-cart or funnel reports: discover the relevant model and fields first, include the required `interval`, and do not invent measure or dimension names. The Semantic Model API can return up to 1,000 rows per query; page when needed. + +## Record-level checks + +Use Abandoned Checkout API query/search only after the analytics question needs record-level evidence, sample checkouts, or link verification: + +```http +POST https://www.wixapis.com/ecom/v1/abandoned-checkout/query +``` + +Query can return up to 100 abandoned checkouts per request, so page through the full period before sampling records. When available, cross-check recovered orders against abandoned checkout IDs, status/activity fields, or recovery attribution. + +## Dashboard checks + +Recovery email automation is Dashboard-managed. Ask the merchant to confirm: + +- the automation is active +- the trigger is abandoned checkout / cart +- sender email is valid +- email content includes a recovery CTA +- no condition accidentally excludes eligible shoppers + +## Root-cause routing + +Route the likely cause: + +- Recovery automation off or misconfigured -> [Troubleshoot Abandoned-Cart Recovery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/abandoned-carts-troubleshoot-recovery) +- Recovery links fail -> [Generate a Recovery Link](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/abandoned-carts-recovery-link) +- Abandonment spike at delivery step -> [Checkout & Cart](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/checkout-cart) and shipping coverage/rate checks +- Incentive or discount issue -> [Pricing & Promotions](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-promotions) + +## Report + +Return: + +- status: OK, WARNING, or CRITICAL +- abandoned checkout volume or trend from Analytics APIs +- recovery rate if available, otherwise say which source data is missing +- change versus baseline +- top suspected cause +- one next action + +## Audit note + +This file is not redundant with the API docs because it defines the health rubric, baseline comparison, Dashboard/manual checks, Analytics/API boundary, and root-cause routing. It must stay honest about inferred metrics: if Analytics models or API data do not expose recovery attribution directly, report volume and evidence instead of fabricating a recovery rate. diff --git a/skills/wix-manage/references/ecommerce/abandoned-carts/ecom-abandoned-carts-recovery-link.md b/skills/wix-manage/references/ecommerce/abandoned-carts/ecom-abandoned-carts-recovery-link.md new file mode 100644 index 00000000..3be3c57d --- /dev/null +++ b/skills/wix-manage/references/ecommerce/abandoned-carts/ecom-abandoned-carts-recovery-link.md @@ -0,0 +1,89 @@ +--- +name: "Abandoned Carts: Recovery Link" +description: Generates a one-click recovery link for an abandoned checkout using the Abandoned Checkout API. Covers listing abandoned checkouts, selecting the correct abandonedCheckoutId, and redirecting the shopper back to checkout. +--- + +# Generate a Recovery Link + +Use this when the merchant wants a one-off link that returns a shopper to the checkout they abandoned. For recurring automated emails, use [Recover Abandoned Carts via Email](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/abandoned-carts-recover-via-email). + +Merchants often say "abandoned cart"; the API entity is **Abandoned Checkout**. + +## Required APIs + +- `POST https://www.wixapis.com/ecom/v1/abandoned-checkout/query` — list abandoned checkouts. The public docs say query can return up to 100 abandoned checkouts per request and supports filters such as `status`, `createdDate`, `updatedDate`, and buyer identifiers. +- `GET https://www.wixapis.com/ecom/v1/abandoned-checkout/{abandonedCheckoutId}` — retrieve and verify one abandoned checkout. +- `GET https://www.wixapis.com/ecom/v1/abandoned-checkout/{abandonedCheckoutId}/redirect-to-checkout?metasiteId={metasiteId}` — redirect the caller to the checkout page. The response is a redirect response, not a normal JSON "create link" object. + +Authentication: the Abandoned Checkout docs require a Wix app or Wix user identity. Permission: `Read Orders`. + +## Step 1: Find the abandoned checkout + +Use the query endpoint for a simple list: + +```http +POST https://www.wixapis.com/ecom/v1/abandoned-checkout/query +``` + +Example filter: + +```json +{ + "query": { + "filter": { + "status": "ABANDONED" + }, + "cursorPaging": { + "limit": 50 + } + } +} +``` + +Use `/ecom/v1/abandoned-checkout/search` when the merchant needs richer filters, such as customer email, date range, cart value, or sort order. + +## Step 2: Confirm the target checkout + +Before generating a link, confirm the abandoned checkout matches the merchant's intended shopper or order context: + +- buyer/contact email or contact ID +- cart total +- created or updated timestamp +- abandoned checkout `id` +- site or `metasiteId` context needed for redirect + +Do not generate a link for a checkout that already converted. + +## Step 3: Redirect to checkout + +```http +GET https://www.wixapis.com/ecom/v1/abandoned-checkout/{abandonedCheckoutId}/redirect-to-checkout?metasiteId={metasiteId} +``` + +The response is expected to be an HTTP redirect, usually `302`, with the checkout URL in the `Location` header. Use the redirected URL in the merchant's own message, support reply, or recovery email CTA only after confirming it belongs to the intended shopper/checkout. + +Example response shape: + +```json +{ + "statusCode": 302, + "headers": [ + { + "key": "Location", + "value": "https://example.wixsite.com/store/checkout?appSectionParams=..." + } + ] +} +``` + +## Guardrails + +- Confirm the shopper can be contacted before sharing a recovery link. +- Treat the link as shopper-specific. Do not publish it broadly. +- If the merchant wants recurring sends, route to the Dashboard automation recipe instead of trying to build an email scheduler here. +- If the API returns a redirect response, extract the `Location` header. Do not invent a `checkoutUrl` or `recoveryUrl` field if the response did not return one. +- If no `Location` header is present, return the status code and headers you received and route to troubleshooting. + +## Audit note + +This file is not redundant with the API docs because it adds selection guardrails, the merchant-facing recovery-message boundary, and the critical response-shape detail: redirect-to-checkout is a `GET` redirect flow, not a JSON link-generation action. diff --git a/skills/wix-manage/references/ecommerce/abandoned-carts/ecom-abandoned-carts-troubleshoot-recovery.md b/skills/wix-manage/references/ecommerce/abandoned-carts/ecom-abandoned-carts-troubleshoot-recovery.md new file mode 100644 index 00000000..5db3a917 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/abandoned-carts/ecom-abandoned-carts-troubleshoot-recovery.md @@ -0,0 +1,94 @@ +--- +name: "Abandoned Carts: Troubleshoot Recovery" +description: Diagnoses abandoned-cart recovery flows that are not sending, not generating usable links, or not recovering shoppers. Covers Dashboard automation checks, email eligibility, Abandoned Checkout API checks, and recovery-rate triage. +--- + +# Troubleshoot Abandoned-Cart Recovery + +Use this when a merchant says abandoned-cart recovery is enabled but messages are not sending, links are not working, or recovery performance is weak. + +Merchants often say "abandoned cart"; the public API entity is **Abandoned Checkout**. + +## Required APIs and Dashboard checks + +| Area | Check | Status | +|---|---|---| +| Dashboard automation | Automation active, trigger/action configured, sender valid, conditions not excluding shoppers | Dashboard-managed | +| Information/reporting | Analytics Data API or Semantic Model API for counts, trends, and recovery performance | Site Analytics read | +| Abandoned checkout lookup | `POST /ecom/v1/abandoned-checkout/query` or `/search` for record-level drill-down | TPA-public | +| Single checkout verification | `GET /ecom/v1/abandoned-checkout/{abandonedCheckoutId}` | TPA-public | +| Checkout redirect | `GET /ecom/v1/abandoned-checkout/{abandonedCheckoutId}/redirect-to-checkout?metasiteId={metasiteId}` | TPA-public | + +## Step 1: Identify the recovery path + +Ask which recovery path the merchant is using: + +- **Dashboard automation:** Wix sends abandoned-cart emails automatically. +- **API-assisted recovery:** An external email/message includes a recovery link generated from the Abandoned Checkout API. + +If they are unsure, start with Dashboard automation checks. + +## Step 2: Branch by likely failure point + +| Symptom | Likely branch | First check | +|---|---|---| +| Emails are not sending | Dashboard automation | Automation active, trigger is abandoned checkout/cart, sender valid | +| Emails send but customers cannot return | API/link path | Redirect endpoint returns `302` with a `Location` header | +| Few shoppers are eligible | Eligibility | Email/contact captured, not opted out, checkout still abandoned | +| Recovery is low but technically working | Performance | Timing, content, shipping/payment/tax surprises | + +## Step 3: Check Dashboard automation + +For Dashboard automation issues, ask the merchant to verify: + +- The automation is active. +- The trigger is abandoned checkout / cart, not checkout started. +- The send action has a valid sender email. +- The email content includes a clear recovery CTA. +- There is no audience, segment, or condition that excludes most abandoned checkouts. + +## Step 4: Check eligibility + +Recovery only works when there is enough shopper context: + +- The checkout captured an email or contact. +- The shopper did not opt out. +- The checkout did not later convert. +- The store did not delete or materially change the cart contents in a way that breaks the return path. + +## Step 5: Check the API path + +If the merchant is generating links programmatically: + +1. Query abandoned checkouts with `POST /ecom/v1/abandoned-checkout/query` or `/search`. +2. Confirm the chosen abandoned checkout is still abandoned. +3. Redirect with `GET /ecom/v1/abandoned-checkout/{abandonedCheckoutId}/redirect-to-checkout?metasiteId={metasiteId}`. +4. Confirm the response is a redirect, usually `302`, and extract the checkout URL from the `Location` header. +5. Test the returned URL before sending it to shoppers. + +If the generated link works but emails do not send, the issue is in the email channel, not the Abandoned Checkout API. + +## Step 6: Triage weak recovery performance + +If emails send and links work but recovery is low: + +- Use Analytics APIs to compare abandoned-cart volume, conversion/recovery performance, and current-period trend against the baseline. +- Compare recovery rate against a rough 5-15% benchmark only when the analytics model or source data supports that metric. +- Check timing. One hour after abandonment is usually a good first send. +- Check whether cart contents render in the message. +- Check whether shipping cost, payment failure, or tax surprises caused the abandonment. +- If abandonment is rising broadly, route to [Recovery Health Monitor](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/abandoned-carts-recovery-health) or checkout troubleshooting. + +## Response shape + +Return a short diagnosis with: + +- recovery path used +- likely failure point +- evidence checked +- next action +- whether the fix is Dashboard, API, checkout, shipping, or pricing related + +## Audit note + +This file is not redundant with API docs because it connects Dashboard automation failures, Abandoned Checkout API verification, eligibility checks, and cross-category root-cause routing into one diagnostic tree. diff --git a/skills/wix-manage/references/ecommerce/checkout/ecom-checkout-agentic-readiness.md b/skills/wix-manage/references/ecommerce/checkout/ecom-checkout-agentic-readiness.md new file mode 100644 index 00000000..fd3c02e7 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/checkout/ecom-checkout-agentic-readiness.md @@ -0,0 +1,51 @@ +--- +name: "Checkout: Agentic Readiness" +description: Checks whether a store is ready for AI shopping agents to discover and buy — catalog data quality for AI discovery, a programmatic test-checkout that proves an agent can complete a purchase, and UCP/agentic-commerce enablement. Triggers on "can an AI agent buy from my store", "agentic readiness", "test agentic checkout", "UCP". +--- + +# Agentic Readiness + +Assess whether AI shopping agents can (a) **discover** the store's products and (b) **complete a purchase** programmatically. There is **no public UCP / agentic-commerce REST API** to toggle — readiness is a function of catalog data quality + a checkout that a non-human buyer can complete. This skill audits both with public APIs and runs a real test-checkout. + +> **UCP / agentic-commerce enablement itself is a platform + Dashboard feature** (no TPA-public API). After the checks below, point the merchant to the Wix Dashboard / agentic-commerce settings to opt in, if available for their site. + +## Part 1 — Catalog data quality for AI discovery + +Agents rank and select products from structured data. Query the catalog and flag products missing fields an agent needs: + +- **Products:** `POST https://www.wixapis.com/stores/v3/products/query` (or v1 if the site is on Catalog V1 — detect first). +- For each product check: `name`, a non-empty `description`, at least one `image`, a `price`, `inStock`/inventory, and **identifiers** (GTIN/SKU/brand) used by shopping agents. + +| Signal | Why agents need it | Flag when | +|---|---|---| +| Title + description | relevance matching | missing/empty | +| Image | result rendering | none | +| Price + currency | comparison/affordability | missing | +| In-stock | don't surface unbuyable items | tracked & 0 | +| GTIN / brand / SKU | disambiguation across catalogs | missing | + +Report a **discovery-readiness score** = % of active products with all signals present. + +## Part 2 — Test agentic checkout (prove an agent can buy) + +Run the public eCommerce purchase flow end-to-end against a real in-stock product to confirm a programmatic buyer can complete it: + +1. **Create a cart** — `POST https://www.wixapis.com/ecom/v1/carts` with one in-stock line item. +2. **Create a checkout** — `POST https://www.wixapis.com/ecom/v1/checkouts` (or create-checkout from the cart). Supply a test buyer email + shipping address. +3. **Verify it resolves** — the checkout returns shipping options, tax, and totals with no blocking error. A `MISSING_*` / `CHECKOUT_*` error here is exactly what blocks an agent. +4. Do **not** place a real order in production; stop at a resolvable checkout (or use a test/sandbox site to call `create-order`). + +**Common blockers an agent hits** (each maps to a fix): +- Guest checkout disabled → agent has no account → **enable guest checkout** (Dashboard; see `ecom-checkout.md`). +- Required custom checkout fields → agent can't fill them → minimize required fields (Dashboard). +- No shipping option for the test address → **fix coverage** (see Shipping & fulfillment → `ecom-shipping-fix-coverage`). +- Minimum order amount above the test cart → note it. + +## Part 3 — Report + +Combine into a readiness verdict: +- **Discovery:** the data-quality score + the top missing-field offenders. +- **Checkout:** pass/fail of the test-checkout + the specific blocker if it failed. +- **Enablement:** direct the merchant to the Dashboard for UCP / agentic-commerce opt-in (no API). + +Prioritize fixes by impact: a failing test-checkout (agents can't buy at all) outranks data-quality gaps (agents buy less). diff --git a/skills/wix-manage/references/ecommerce/goal-reduce-cart-abandonment.md b/skills/wix-manage/references/ecommerce/checkout/ecom-checkout-reduce-abandonment.md similarity index 89% rename from skills/wix-manage/references/ecommerce/goal-reduce-cart-abandonment.md rename to skills/wix-manage/references/ecommerce/checkout/ecom-checkout-reduce-abandonment.md index e7ac3666..de7b24f0 100644 --- a/skills/wix-manage/references/ecommerce/goal-reduce-cart-abandonment.md +++ b/skills/wix-manage/references/ecommerce/checkout/ecom-checkout-reduce-abandonment.md @@ -1,24 +1,12 @@ --- -name: "Goal: Reduce Cart Abandonment" +name: "Checkout: Reduce 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) +> - [Flow: Fix Coverage Gaps](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-fix-coverage-gaps) — shipping coverage gaps block checkout entirely +> - [Setup Store Pickup Location](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-pickup-local-delivery) 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. diff --git a/skills/wix-manage/references/ecommerce/checkout/ecom-checkout-store-health.md b/skills/wix-manage/references/ecommerce/checkout/ecom-checkout-store-health.md new file mode 100644 index 00000000..904923d7 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/checkout/ecom-checkout-store-health.md @@ -0,0 +1,35 @@ +--- +name: "Checkout: Store Health Monitor" +description: Periodic technical health check of the checkout/cart path — test the checkout flow end-to-end, detect configuration drift, and surface checkout-blocking issues before they cost sales. Triggers on "store health", "is my checkout working", "periodic checkout check", "store health monitor". +--- + +# Store Health Monitor + +A periodic, technical check of whether the store can actually take orders — distinct from the conversion-focused [Reduce Abandonment](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/checkout-reduce-abandonment) (why buyers leave) and [Troubleshoot Drop-off](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/checkout-troubleshoot-delivery-drop-off) (a reported problem). Run this proactively (e.g. as a scheduled digest) and report only what's broken or drifting. + +## Check 1: Checkout flow works end-to-end + +Reuse the test-checkout from [Agentic Readiness](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/checkout-agentic-readiness) → Part 2: create a cart with a real in-stock item, create a checkout, and confirm it resolves (shipping options + tax + totals, no blocking error). A failure here is **CRITICAL** — the store cannot take orders. + +## Check 2: Configuration drift + +Compare current config against a healthy baseline; flag changes that block or degrade checkout: +- **Payment provider connected** — no active provider → can't collect payment (CRITICAL). +- **Shipping coverage** — regions with zero shipping options (see `ecom-shipping-fix-coverage`) → buyers in those regions can't complete checkout. +- **Tax configured** — for sites that require it (see Tax category). +- **Guest checkout / required fields** — newly-added required custom fields can silently raise abandonment. + +## Check 3: Order-flow anomalies (error signal) + +Without an app-error API, infer trouble from order/checkout data: +- **Abandoned-checkout spike** — route recovery-performance analysis to [Abandoned Carts: Recovery Health](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/abandoned-carts-recovery-health). A sudden jump can still signal a checkout problem (payment failing, shipping gap, surprise cost). +- **Orders stalled** — recent orders stuck unpaid/unfulfilled (Orders query) relative to normal volume. + +## Report + +Severity-ranked digest: +- **CRITICAL** — test-checkout fails, no payment provider, or no shipping coverage. The store is losing every affected sale now. +- **WARNING** — abandonment spike, drifted config, tax gaps. +- **OK** — checkout resolves and config matches baseline; note the green state. + +For each issue, link the fixing skill (shipping coverage, tax, checkout config) rather than re-explaining it. diff --git a/skills/wix-manage/references/ecommerce/troubleshoot-checkout-delivery-dropoff.md b/skills/wix-manage/references/ecommerce/checkout/ecom-checkout-troubleshoot-dropoff.md similarity index 95% rename from skills/wix-manage/references/ecommerce/troubleshoot-checkout-delivery-dropoff.md rename to skills/wix-manage/references/ecommerce/checkout/ecom-checkout-troubleshoot-dropoff.md index 445186ac..5928cc6c 100644 --- a/skills/wix-manage/references/ecommerce/troubleshoot-checkout-delivery-dropoff.md +++ b/skills/wix-manage/references/ecommerce/checkout/ecom-checkout-troubleshoot-dropoff.md @@ -1,7 +1,6 @@ --- -name: "Troubleshoot: Checkout Delivery Drop-off" +name: "Checkout: Troubleshoot Delivery Drop-off" description: Diagnostic tree for when delivery step conversion is below benchmark. Correlates shipping issues with checkout abandonment and calculates revenue impact. -layer: troubleshoot --- # Troubleshoot: Checkout Delivery Drop-off @@ -100,7 +99,7 @@ Follow this sequence to systematically identify the root cause: ### 5.4 Check rate pricing sanity - Are any rates exceeding 15% of AOV? - Is `multiplyByQuantity` enabled on any rate? -- See the **Guardrail: Rate Pricing Sanity** skill for detailed checks. +- See the rate-pricing-sanity checks inlined in [Shipping: Optimize Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-optimize-rates). ### 5.5 Check backup rates - Are backup rates configured on carriers? diff --git a/skills/wix-manage/references/ecommerce/ecom-abandoned-carts.md b/skills/wix-manage/references/ecommerce/ecom-abandoned-carts.md new file mode 100644 index 00000000..b2e9ec7d --- /dev/null +++ b/skills/wix-manage/references/ecommerce/ecom-abandoned-carts.md @@ -0,0 +1,61 @@ +--- +name: "Abandoned Carts" +description: Abandoned checkout recovery and recapture for an eCommerce store - view abandoned checkouts, recover them with Dashboard automation or API-generated recovery links, troubleshoot recovery flows, and monitor recovery health. +--- + +# Abandoned Carts + +Recover shoppers who already left checkout. Merchants often say "abandoned carts"; the Wix API surface calls these **Abandoned Checkouts**. Use this category for abandoned-checkout recovery emails, recovery links, recovery troubleshooting, and recovery performance monitoring. + +For information and reporting queries, prefer **Analytics APIs**. Use the Abandoned Checkout API only when the agent needs to inspect or act on specific abandoned checkout records. + +**Abandoned carts is NOT:** +- Reducing live checkout drop-off before the shopper leaves -> see **Checkout & Cart**. +- Shipping cost or delivery-step friction -> see **Shipping**. +- Discounts and incentives used in recovery emails -> see **Pricing & Promotions**. + +> **Before dispatching** - confirm MerchantContext is loaded. If `siteData.country` is not in your conversation context, load it via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context). Skip if already loaded. +> +> **Promotion dispatch.** Score each entry below by the merchant's query -> `intent:*` tags. Load the highest-scoring entry. No match -> base recipe. + +### Recovery actions + +> - [Recover abandoned carts via email](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/abandoned-carts-recover-via-email) — tags: `[intent:recover-email]` · priority 0 · *Dashboard-configured automation; Abandoned Checkout API can verify eligibility/activity but does not configure recurring sends* +> - [Generate a recovery link / resume checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/abandoned-carts-recovery-link) — tags: `[intent:recovery-link]` · priority 0 · *Abandoned Checkout API: find checkout, confirm target, redirect to checkout* + +### Diagnose and monitor + +> - [Troubleshoot abandoned-cart recovery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/abandoned-carts-troubleshoot-recovery) — tags: `[intent:troubleshoot-recovery]` · priority 0 +> - [Recovery health monitor](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/abandoned-carts-recovery-health) — tags: `[intent:recovery-health]` · priority 0 + +### Info + +> - [Abandoned-cart analytics and reports](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/query-semantic-model-data) — tags: `[intent:view-abandoned]`, `[intent:information]`, `[intent:reporting]` · priority 0 · **Analytics API route, no dedicated skill**. Use Analytics Data API or Semantic Model API for counts, trends, conversion/recovery performance, and reporting. Use Abandoned Checkout API only for drilling into specific records after the analytics question is scoped. + +### API boundary + +| Merchant need | Preferred surface | +|---|---| +| "How many abandoned carts did I have?" | Analytics APIs | +| "Did abandonment/recovery trend change?" | Analytics APIs | +| "Show abandoned-cart report by date or channel" | Semantic Model API, after discovering available fields | +| "Find this shopper's abandoned checkout" | Abandoned Checkout API query/search | +| "Generate a link to resume checkout" | Abandoned Checkout API redirect endpoint | + +## Tag matching examples + +| Merchant query | Match | +|---|---| +| "Show me abandoned carts from this week" | Analytics API route: `intent:view-abandoned` | +| "Create an automated abandoned cart email" | `ecom-abandoned-carts-recover-email` via `intent:recover-email` | +| "Send this customer a link to finish checkout" | `ecom-abandoned-carts-recovery-link` via `intent:recovery-link` | +| "My abandoned cart emails are not sending" | `ecom-abandoned-carts-troubleshoot-recovery` via `intent:troubleshoot-recovery` | +| "Did abandoned checkout recovery get worse this month?" | `ecom-abandoned-carts-recovery-health` via `intent:recovery-health` | + +## Base recipe + +If nothing matches, ask **one** clarifying question: + +> "Do you want to **view abandoned checkouts**, **recover them with emails or links**, or **troubleshoot/monitor** recovery performance?" + +Map the answer to an `intent:*` tag and re-dispatch. If the merchant is asking how to stop customers from leaving checkout in the first place, route to **Checkout & Cart** instead. diff --git a/skills/wix-manage/references/ecommerce/ecom-checkout.md b/skills/wix-manage/references/ecommerce/ecom-checkout.md new file mode 100644 index 00000000..aa36a476 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/ecom-checkout.md @@ -0,0 +1,44 @@ +--- +name: "Checkout & Cart" +description: Checkout and cart experience - reducing live checkout/cart abandonment, troubleshooting checkout failures and delivery-step drop-off, checkout policies, and pointers to the Dashboard-managed checkout settings (guest checkout, minimum order, custom fields). +--- + +# Checkout & Cart + +Improve and fix the checkout/cart experience before an order is placed - reduce live checkout drop-off, diagnose why customers cannot complete checkout, configure checkout policies, and adjust the checkout settings that drive conversion. + +**Checkout & cart is NOT:** +- Shipping rates / regions / pickup setup → see **Shipping & fulfillment** (though delivery-step friction is the #1 abandonment cause and is handled here + there). +- Discounts / coupons applied at checkout → see **Pricing & promotions**. +- Tax shown at checkout → see **Tax**. +- Recovery after the shopper already left checkout → see **Abandoned Carts**. + +> **Heads-up — much of checkout config is Dashboard-only.** The public Checkout Settings API covers only checkout-footer **policies** and payment-step **checkboxes**. Guest checkout, minimum order amount, custom checkout fields, and checkout upsell are **not exposed via a TPA-public API** — route the merchant to the Wix Dashboard for those. + +> **Before dispatching** — confirm MerchantContext is loaded. If `siteData.country` is not in your conversation context, load it via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context). Skip if already loaded. +> +> **Promotion dispatch.** Score each entry below by the merchant's query → `intent:*` tags. Load the highest-scoring entry. No match → base recipe. + +### Reduce abandonment & troubleshoot (recipes) + +> - [Reduce checkout/cart abandonment (delivery-step friction)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/checkout-reduce-abandonment) — tags: `[intent:reduce-abandonment]` · priority 0 +> - [Troubleshoot checkout failure / delivery drop-off](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/checkout-troubleshoot-delivery-drop-off) — tags: `[intent:troubleshoot-checkout]` · priority 0 +> - [Agentic readiness / test agentic checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/checkout-agentic-readiness) — tags: `[intent:agentic]` · priority 0 · *catalog data-quality audit + programmatic test-checkout; UCP enablement is Dashboard* +> - [Store health monitor (periodic)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/checkout-store-health-monitor) — tags: `[intent:store-health]` · priority 0 · *test checkout + config-drift + anomaly checks* +> - Recover abandoned checkouts after the shopper leaves — tags: `[intent:recover-email]`, `[intent:view-abandoned]`, `[intent:recovery-link]` · **see [Abandoned Carts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/abandoned-carts)** + +### Checkout configuration + +> - [Set checkout policies / payment-step checkboxes](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/checkout-settings) — tags: `[intent:checkout-policies]` · **API doc, no skill** (per §7.5 — Checkout Settings API) +> - Enable **guest checkout** — tags: `[intent:guest-checkout]` · **Wix Dashboard** (Settings → Checkout) — no TPA-public API +> - Set **minimum order amount** — tags: `[intent:min-order]` · **Wix Dashboard** — no TPA-public API +> - **Customize checkout fields** / add a field — tags: `[intent:custom-fields]` · **Wix Dashboard** (custom checkout fields) — no TPA-public API +> - **Product recommendations at checkout** — tags: `[intent:checkout-recs]` · **Wix Dashboard** / Stores upsell settings — no TPA-public API + +## Base recipe (fallback) + +If nothing matches, ask **one** clarifying question: + +> "Do you want to (a) **reduce live checkout drop-off**, (b) **configure** checkout (guest checkout, minimum order, fields — most are in the Wix Dashboard), or (c) **recover shoppers who already abandoned checkout**?" + +Map the answer to an `intent:*` tag and re-dispatch. For recovery/recapture, route to **Abandoned Carts**. For configuration intents with no public API, give the merchant the Dashboard path directly. diff --git a/skills/wix-manage/references/ecommerce/ecom-fulfillment.md b/skills/wix-manage/references/ecommerce/ecom-fulfillment.md new file mode 100644 index 00000000..4e789af7 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/ecom-fulfillment.md @@ -0,0 +1,63 @@ +--- +name: "Fulfillment" +description: Post-purchase fulfillment operations for eCommerce orders - find unshipped or problematic orders, mark orders fulfilled, update tracking, handle partial and bulk fulfillment, route invoice/packing-slip requests, and direct shipping-label export to Dashboard. +--- + +# Fulfillment + +Handle what happens after an order is placed: find orders that need shipping attention, create fulfillments, update tracking, handle partial or bulk fulfillment, and route shipping documents correctly. + +**Fulfillment is NOT:** +- Shipping rates, delivery regions, pickup, or free-shipping setup -> see **Shipping**. +- Checkout drop-off before an order is placed -> see **Checkout & Cart**. +- Refunds and payments -> route to the existing Get Paid/payment docs or Dashboard-supported payment flows. Order cancellations belong to **Orders** when that category is available. + +> **Before dispatching** - confirm MerchantContext is loaded. If `siteData.country` is not in your conversation context, load it via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context). Skip if already loaded. +> +> **Promotion dispatch.** Score each entry below by the merchant's query -> `intent:*` tags. Load the highest-scoring entry. No match -> base recipe. + +### Fulfillment actions + +> - [Fulfill orders & tracking](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/fulfillment-fulfill-orders-tracking) - tags: `[intent:fulfill-order]`, `[intent:update-tracking]`, `[intent:partial-fulfillment]` - priority 0 - *Fulfillments API: create fulfillment, update tracking, partial fulfillment* +> - [Bulk fulfill orders](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/fulfillment-bulk-fulfill-orders) - tags: `[intent:bulk-fulfill]` - priority 0 - *batch fulfillment with partial-failure handling* + +### Lookup and document routes + +> - Find unshipped / problematic orders - tags: `[intent:find-unshipped]` - **API route, no dedicated skill** - use Orders search with fulfillment status filters such as `NOT_FULFILLED` or `PARTIALLY_FULFILLED`; then route to a fulfillment action if the merchant wants to mutate orders. +> - Orders needing shipping label - tags: `[intent:orders-needing-label]` - **main-file route** - find candidate paid, unfulfilled orders via Orders search; actual label export/printing is Dashboard. +> - Print packing slip / invoice - tags: `[intent:order-invoice]` - **API route, no dedicated skill** - eCommerce Orders Invoice API (`wix.ecom.orders.v1.invoice`) when available for the requested document. +> - Export shipping labels - tags: `[intent:shipping-labels]` - **Wix Dashboard** - no verified public API route in this repo. + +## API and Dashboard status + +| Capability | Route | Status | +|---|---|---| +| Create one fulfillment for one order | `POST /ecom/v1/fulfillments/orders/{orderId}/create-fulfillment` | TPA-public | +| Update tracking / fulfillment fields | `PATCH /ecom/v1/fulfillments/{fulfillmentId}/orders/{orderId}` | TPA-public | +| List fulfillments for one order | `GET /ecom/v1/fulfillments/orders/{orderId}` | TPA-public | +| Bulk create fulfillments | `POST /ecom/v1/fulfillments/orders/bulk/create-fulfillments` | TPA-public | +| Find orders needing fulfillment | `POST /ecom/v1/orders/search` with fulfillment/payment/status filters | TPA-public | +| Export / buy shipping labels | Wix Dashboard | Dashboard-managed in this repo | + +## Tag matching examples + +| Merchant query | Match | +|---|---| +| "I shipped order #1052" | `ecom-fulfillment-fulfill-orders` via `intent:fulfill-order` | +| "Add tracking number for order #1052" | `ecom-fulfillment-fulfill-orders` via `intent:update-tracking` | +| "I can only ship 2 of the 3 items now" | `ecom-fulfillment-fulfill-orders` via `intent:partial-fulfillment` | +| "Fulfill all orders from today" | `ecom-fulfillment-bulk-fulfill-orders` via `intent:bulk-fulfill` | +| "Which orders need shipping labels today?" | main-file route via `intent:orders-needing-label` | +| "Cancel order #1053" | Orders category, not Fulfillment | + +## Base recipe + +If nothing matches, ask **one** clarifying question: + +> "Do you want to **find orders that need fulfillment**, **mark/update fulfillments**, **bulk fulfill orders**, or **print invoices/labels**?" + +Route shipping setup questions back to **Shipping**. + +## Audit note + +This file is not redundant with Wix API docs because it owns the routing boundary between fulfillment, orders, payments/refunds, shipping setup, and Dashboard-only label work. The child fulfillment skills carry the mutation guardrails; this file keeps shallow lookup/document routes in the 80% main path. diff --git a/skills/wix-manage/references/ecommerce/ecom-load-context.md b/skills/wix-manage/references/ecommerce/ecom-load-context.md new file mode 100644 index 00000000..099798c4 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/ecom-load-context.md @@ -0,0 +1,114 @@ +--- +name: "eCommerce: Load Context" +description: L1-level context loader for the eCommerce domain. Loads ONLY general / cross-cutting site data (siteId, country, region, industry, currency, AOV, traffic signals). Called from every eCommerce category's default.md before tag-matching. Per-category runtime state (Tax calculator, Catalog version, payment provider, …) is detected inside the owning category, NOT here. Skip if already loaded. +--- + +# eCommerce: Load Context + +> **L1 loader pattern.** Each L1 domain (eCommerce, Stores, Get-paid, Contacts, …) owns its own context loader. This file is the **eCommerce** L1 loader. Other L1s have their own (e.g. `stores-load-context.md` will detect Catalog V1/V3 for Stores categories). The boilerplate (Step 1 + 2) is small; the **field list and runtime detections differ by L1**. + +> **When to run.** Called from the dispatch block of any eCommerce category's `default.md` (Tax, Pricing & promotions, …) before tag-matching. Run **once per session**. If `siteData.country` is already in your conversation context, skip the API calls below and return immediately — every subsequent eCommerce category entry reuses the loaded data. + +This is the canonical extract of Steps 1 + 3 from today's `recommend-ecommerce-strategy.md`, scoped to the fields eCommerce categories actually need. + +## Step 1 — Resolve siteId + +If a `siteId` is not already known, call `ListWixSites`: + +``` +ListWixSites() +``` + +- If the merchant referenced a site by name, match it. +- If exactly one site exists, auto-select it. +- Otherwise, ask the merchant which site to use. + +**Do not proceed without a `siteId`.** + +## Step 2 — Load business profile (the canonical endpoint) + +Same call today's `recommend-ecommerce-strategy.md` Step 3 makes. The field list below is the **eCommerce** subset — orchestrator-needed metrics (visitors / orders / GPV → AOV) plus locale/currency/industry used for dispatch tags and recommendations. + +``` +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" + ] + } +) +``` + +Extract each field into conversation context as `siteData`: + +| Field in response | Maps to | Notes | +|---|---|---| +| `fields.language.aSingleValue.aString` | `siteData.language` | Locale code (e.g. `en-US`) | +| `fields.merchant_business_country.aSingleValue.aString` | `siteData.country` | ISO-3166-1 alpha-2 | +| `fields.suggested_main_industry.aSingleValue.aString` | `siteData.industry` | Used by Pricing orchestrator's goal classification | +| `fields.suggested_sub_industry.aSingleValue.aString` | `siteData.subIndustry` | Optional | +| `fields.last_30_days_distinct_visitors.aSingleValue.aLong` | `siteData.visitors30d` | **Returned as JSON string** — `parseInt` before arithmetic | +| `fields.last_30_days_orders_count.aSingleValue.aLong` | `siteData.orders30d` | parseInt | +| `fields.online_gpv_last_30_days.aSingleValue.aLong` | `siteData.gpv30d` | parseInt | +| `fields.payment_currency.aSingleValue.aString` | `siteData.currency` | ISO-4217 | + +Missing fields ⇒ no data for that field (don't fabricate). If `merchant_business_country`, `suggested_main_industry`, or `online_gpv_last_30_days` are missing or null, surface to the merchant: "Cannot resolve required site data: ." and stop. + +**Derived value:** `siteData.aov = parseInt(gpv30d) / parseInt(orders30d)` — in `siteData.currency` units. + +## Step 3 — Derive region (used by dispatch context tags) + +From `siteData.country`, set `siteData.region`: +- `BR | AR | MX | CL | CO | PE` → `LATAM` +- EU member states (`DE | FR | IT | ES | NL | BE | PL | SE | IE | AT | PT | FI | DK | CZ | HU | GR | RO | BG | HR | SK | SI | LT | LV | EE | CY | MT | LU`) → `EU` +- `JP | CN | KR | SG | AU | NZ | IN | TH | ID | MY | PH | VN | HK | TW` → `APAC` +- otherwise → `null` + +(UK is **not** in `region:EU`. AU/NZ are in `region:APAC` but Tax inclusive-pricing rules differ — handled inside Tax promotions.) + +## Step 4 — Return + +Return immediately. Subsequent eCommerce category dispatches read `siteData.*` from conversation context without re-fetching. If the agent crosses into a different L1 (e.g. Stores) within the same session, that L1's loader will see `siteData.country` already loaded, skip its Steps 1-3, and only fire its own general derivations. + +## Architectural rule — general site data only + +**This file must contain only general / cross-cutting site data** — fields that **every** category in this L1 needs. It must **not** include L3-category-specific runtime detection (e.g. Tax calculator, Catalog V1/V3, payment-provider state, shipping-coverage state). + +Reasoning: +- Per-category detect calls accumulate cost on every session entry, even when the agent never visits that category. +- L3-specific state can use APIs that aren't TPA-public (e.g. the Wix Tax FQDNs are `exposure: INTERNAL`); if the L1 loader depends on them, the entire L1 fails to load. Keeping the loader general-only contains the blast radius. +- Per-category state can change independently of the merchant; loading it eagerly invites stale-data bugs. + +**Where category-specific runtime data is detected instead:** inside the category's `default.md` (Step before dispatch) or inside the specific promotion that needs it. The L1 loader does **not** prime per-category fields; the category does its own detection lazily, only when its own intent dispatch fires. + +Concretely for the categories we know about: +- **Tax** — calculator detection (Manual vs Avalara) belongs in `ecom-tax.md` (the merged category-doc + dispatcher) or in each Tax promotion when it runs. Not here. +- **Catalog** (when Stores migrates) — V1/V3 detection belongs in `catalog/stores-catalog-default.md`, not in a Stores L1 loader. +- **Payments & finance** (when Get-paid migrates) — payment-provider state belongs in `finance-and-payments/get-paid-finance-default.md`. + +## What this file does NOT do + +- **Does not detect per-category runtime state** (see architectural rule above). +- **Does not load tracking history.** Orchestrator-specific — only `ecom-pricing-run-a-sale` and similar load it (today's `recommend-ecommerce-strategy` Step 2). +- **Does not load catalog analytics.** Orchestrator-specific. +- **Does not load non-eCommerce L1 fields** (catalog V1/V3, payment provider, …). Those belong inside the owning L1's category-level files (per the architectural rule). +- **Does not enforce dispatch.** The category's `default.md` is what scores tags and picks a promotion — this file only fills general site context. + +## Pattern for future L1 loaders + +When a new L1 domain is migrated to the routing tree, author a `-load-context.md` at its root: + +- `references/stores/stores-load-context.md` — Stores L1 loader. Steps 1-3 same boilerplate, Step 4 runtime-detects Catalog version (V1/V3) and any other Stores-specific fields. +- `references/get-paid/get-paid-load-context.md` — Get-paid L1 loader. Step 4 inspects payment provider state, enabled methods. +- `references/contacts/contacts-load-context.md` — Contacts L1 loader. Possibly minimal — most CRM ops don't need runtime detection. + +Each lives sibling to its L1's category-docs. Each is referenced from every category's `default.md` within its L1. Skip-if-loaded check across L1s makes cross-L1 sessions cost-free. diff --git a/skills/wix-manage/references/ecommerce/ecom-orders.md b/skills/wix-manage/references/ecommerce/ecom-orders.md new file mode 100644 index 00000000..da1c72d4 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/ecom-orders.md @@ -0,0 +1,61 @@ +--- +name: "Orders" +description: eCommerce order lifecycle and lookup - search orders, view order details/counts, cancel orders, diagnose pending orders, and route fulfillment, refunds, payments, returns, and notifications to the right owner. +--- + +# Orders + +Use this category for eCommerce order lookup and lifecycle routing: search orders, get order details, count recent orders, cancel orders, diagnose pending/stuck orders, and distinguish order lifecycle from fulfillment, payments, refunds, catalog, and inventory. + +**Orders is NOT:** +- Fulfillment/shipping/tracking -> see [Fulfillment](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/fulfillment). +- Refund execution or payment reporting -> route to the existing Get Paid/payment docs or Dashboard-supported payment flows. +- Product catalog or inventory updates -> see Stores Catalog / Stores Inventory. + +> **Before dispatching** - confirm MerchantContext is loaded. If `siteData.country` is not in your conversation context, load it via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context). Skip if already loaded. +> +> **Promotion dispatch.** Score each entry below by the merchant's query -> `intent:*` tags. Load the highest-scoring entry. No match -> base recipe. + +### Order lifecycle actions + +> - [Cancel Order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/orders-cancel-order) - tags: `[intent:cancel-order]` - priority 0 - *destructive order lifecycle mutation; confirm restock/email/payment implications before canceling* + +### Main-file API routes + +Use the main file, not a separate skill, for common read-only Orders intents: + +| Intent | Merchant examples | API route | +|---|---|---| +| View recent orders / order counts | "Show me today's orders"; "How many orders came in this week?" | `POST /ecom/v1/orders/search` with date filters and paging | +| Get order details | "Show me order #1052" | search by number/display context, then `GET /ecom/v1/orders/{id}` | +| Search orders by customer/criteria | "Show me orders from California"; "Find orders for jane@example.com" | `POST /ecom/v1/orders/search` with supported filters | +| Diagnose pending/stuck order | "Order is stuck in pending" | Get/search order, inspect `status`, `paymentStatus`, `fulfillmentStatus`, and route to Payments/Fulfillment/Checkout as needed | + +### Explicit handoffs and Dashboard routes + +> - Approve an order - tags: `[intent:approve-order]` - **unverified API route**. Do not write an approve-order skill until the exact public method is verified. Diagnose status first; if approval depends on offline payment/manual approval, route to Dashboard or verified Orders/Payments docs. +> - Handle a return - tags: `[intent:return-order]` - **Dashboard / workflow route**. Do not treat "return" as an immediate refund. If the merchant asks to refund, route to verified Get Paid/payment docs or Dashboard guidance. +> - Create a manual order with a pay link - tags: `[intent:manual-order-pay-link]` - **Dashboard / partial route**. Payment links are covered by [Create Payment Links](https://dev.wix.com/docs/api-reference/business-management/get-paid/skills/create-payment-links), but manual order creation must be verified before an execution skill is created. +> - Contact customer about order - tags: `[intent:contact-customer]` - **Dashboard-only / unverified messaging route** unless the message is specifically a payment link send. +> - Configure new-order notifications - tags: `[intent:order-notifications]` - **Wix Dashboard**. No verified public API route in this repo. + +## Required APIs + +- [Search Orders](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/search-orders): `POST https://www.wixapis.com/ecom/v1/orders/search` +- [Get Order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/get-order): `GET https://www.wixapis.com/ecom/v1/orders/{id}` +- [Cancel Order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/cancel-order): `POST https://www.wixapis.com/ecom/v1/orders/{id}/cancel` + +## Base recipe + +1. Classify the request as lookup/search, cancel, pending diagnosis, return, payment/refund, fulfillment, or Dashboard-only setup. +2. For lookup/search, use Orders Search/Get and keep the flow read-only. +3. For cancel, load the dedicated cancel-order skill. +4. For "pending" or "stuck," inspect order `status`, `paymentStatus`, and `fulfillmentStatus`, then route: + - payment issue -> Payments + - fulfillment issue -> Fulfillment + - checkout/order creation issue -> Checkout or Orders depending on evidence +5. For returns, payment refunds, or payment collection, do not mutate through Orders without the correct owner skill. + +## Audit note + +This file is not redundant with the Orders API docs because it establishes ownership and routing boundaries: generic order lookup belongs here, fulfillment actions belong to Fulfillment, money movement belongs to Get Paid, and Dashboard-only order operations must not be overclaimed as API-supported. diff --git a/skills/wix-manage/references/ecommerce/ecom-pricing.md b/skills/wix-manage/references/ecommerce/ecom-pricing.md new file mode 100644 index 00000000..001e44bc --- /dev/null +++ b/skills/wix-manage/references/ecommerce/ecom-pricing.md @@ -0,0 +1,75 @@ +--- +name: "Pricing & Promotions" +description: All discount, coupon, sale, bundle, and promotional pricing for the store. Includes strategic flows (run a sale, multi-channel pricing) and operational troubleshooting (discount not applying). +--- + +# Pricing & Promotions + +Discount rules, coupon codes, sales, ribbons, bundles, tiered pricing, and the strategic side of "run a promotion to grow revenue". + +**Pricing & promotions is NOT:** +- The product price itself or its description/image → see **Catalog** (those are product fields). +- A standing $0 shipping option/region rate → see **Shipping & fulfillment**. +- Refunding a previous discounted order → route to verified Get Paid/payment docs or Dashboard guidance. + +> **Before dispatching** — confirm MerchantContext is loaded. If `siteData.country` is not in your conversation context, load it via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context). Skip if already loaded. +> +> **Promotion dispatch.** Score each entry below by (a) the merchant's query → `intent:*` tags, (b) MerchantContext → context tags. Load the **highest-scoring** entry. Ties → highest `priority`. No match → follow the base recipe at the bottom. + +### Actions — concrete operations + +> - [Create coupon](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-coupon) — tags: `[intent:create-coupon]` · priority 0 +> - [Create discount rule (auto-apply)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:create-discount-rule]` · priority 0 +> - [Add sale ribbon / new ribbon](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:add-ribbon]` · priority 0 · *ribbons are configured via Discount Rules; same recipe* +> - [Schedule a future sale](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:schedule-sale]` · priority 0 · *uses Discount Rules with `startTime` in the future* + +### Business flows — the orchestrator + +The single business-flow orchestrator (today's `recommend-ecommerce-strategy`, renamed/moved to `ecom-pricing-run-a-sale`) handles all strategic discount intents. It classifies internally (SEASONAL / UPSELL_BOOST / STOCK_MOVER / BUNDLE_AND_SAVE / ABANDONED_CART) and loads its `goal-*` / `flow-*` support files (flat siblings in this folder) from there. + +> - [Run a sale / promotion strategy](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-run-a-sale-recommend-e-commerce-strategy) — tags: `[intent:run-a-sale]` · priority 0 +> - [Boost my business / increase sales](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-run-a-sale-recommend-e-commerce-strategy) — tags: `[intent:boost-business]` · priority 0 +> - [Seasonal / holiday promotion](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-run-a-sale-recommend-e-commerce-strategy) — tags: `[intent:seasonal-promo]` · priority 0 +> - [Clearance / move slow stock](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-run-a-sale-recommend-e-commerce-strategy) — tags: `[intent:clearance]` · priority 0 +> - [Increase AOV (bundle / upsell)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-run-a-sale-recommend-e-commerce-strategy) — tags: `[intent:increase-aov]` · priority 0 + +### Info / troubleshoot / recommendation + +> - [Discount not applying — diagnose](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-discount-not-applying) — tags: `[intent:troubleshoot]` · priority 0 +> - [View active discounts (Coupons API)](https://dev.wix.com/docs/api-reference/business-solutions/coupons/coupons/query-coupons) — tags: `[intent:view-active-discounts]` · priority 0 · **API doc, no skill** (per §7.5) +> - [View active discounts (Discount Rules API)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/discount-rules/query-discount-rules) — tags: `[intent:view-active-rules]` · priority 0 · **API doc, no skill** +> - [Coupon usage stats](https://dev.wix.com/docs/api-reference/business-solutions/coupons/coupons/get-coupon-usage) — tags: `[intent:coupon-usage-stats]` · priority 0 · **API doc, no skill** +> - [Pricing & discount health (periodic review)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-discount-health) — tags: `[intent:pricing-health]` · priority 0 · *sweep active rules/coupons for conflicts, stale sales, margin erosion* +> - Competitive pricing check (how do my prices compare?) — tags: `[intent:competitive-pricing]` · *no Wix API for competitor data — advise the merchant to benchmark externally (Google Shopping / market research); Wix only exposes their own catalog prices via Catalog API* + +### Cross-category routes (handled in another category) + +> - [Change product price](https://dev.wix.com/docs/api-reference/business-solutions/stores/products-v3/update-product) — tags: `[intent:change-price]` · *price is a product field — Catalog API* +> - [Set compare-at price](https://dev.wix.com/docs/api-reference/business-solutions/stores/products-v3/update-product) — tags: `[intent:set-compare-at]` · *Catalog* +> - [Free shipping over $X (promo rule)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:free-shipping-promo]` · *belongs here as a promo rule; a $0 shipping rate is Shipping* + +## Tag matching + +The agent matches the merchant's natural-language query to an `intent:*` tag (cues are in each promotion file's `description`), AND matches MerchantContext to any context tags. A promotion's tags must ALL be satisfied for it to be eligible. Among eligible promotions, the one with the highest tag-count wins; ties broken by `priority`. + +### Worked examples + +| Merchant query | MerchantContext | Match | +|---|---|---| +| "Create a 20% off coupon" | any | `ecom-pricing-create-coupon` via `[intent:create-coupon]` | +| "Run a Black Friday sale" | any | `ecom-pricing-run-a-sale` via `[intent:run-a-sale]` (orchestrator classifies as SEASONAL internally) | +| "Help me boost my sales" | any | `ecom-pricing-run-a-sale` via `[intent:boost-business]` | +| "My coupon code XMAS isn't working" | any | `ecom-pricing-troubleshoot-not-applying` | +| "Show me my active discounts" | any | `query-coupons` API doc (no skill — per §7.5) | +| "Change the price of product Y" | any | Catalog cross-route (re-dispatch to Catalog when that category exists) | + +## Base recipe (fallback) + +If nothing matches, the merchant query is too vague. Ask **one** clarifying question: + +> "Do you want to (a) **create** a specific discount/coupon now, (b) **strategize** a sale or promotion campaign, or (c) **fix** a discount that isn't applying?" + +Map the answer → re-dispatch: +- (a) → `ecom-pricing-create-coupon` (default for "create a discount") +- (b) → `ecom-pricing-run-a-sale` +- (c) → `ecom-pricing-troubleshoot-not-applying` diff --git a/skills/wix-manage/references/ecommerce/ecom-shipping.md b/skills/wix-manage/references/ecommerce/ecom-shipping.md new file mode 100644 index 00000000..dbf23b64 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/ecom-shipping.md @@ -0,0 +1,62 @@ +--- +name: "Shipping" +description: Shipping setup for an eCommerce store - shipping rates and rules, delivery regions/coverage, store pickup, free-shipping thresholds, rate optimization, and wrong-rate troubleshooting. +--- + +# Shipping + +Set up and tune how a store ships — what rates to charge, which regions are covered, pickup/local-delivery options, free-shipping thresholds, and diagnosing wrong or missing shipping at checkout. + +**Shipping & fulfillment is NOT:** +- Tax on shipping or destination tax → see **Tax**. +- The checkout/delivery step conversion itself → see **Checkout & cart**. +- Marking orders fulfilled, updating tracking, bulk fulfillment, invoices, or shipping labels → see **Fulfillment**. +- Order lifecycle (approve/cancel/search an order) → **Orders** when available; refunds/payments → existing Get Paid/payment docs or Dashboard guidance. + +> **Before dispatching** — confirm MerchantContext is loaded. If `siteData.country` is not in your conversation context, load it via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context). Skip if already loaded. +> +> **Promotion dispatch.** Score each entry below by (a) the merchant's query → `intent:*` tags, (b) MerchantContext → context tags. Load the **highest-scoring** entry with `ReadFullDocsArticle`. Ties → highest `priority`. No match → follow the base recipe at the bottom. +> +> **API reference.** All shipping endpoints (Shipping Options + Delivery Profiles) are documented inline in [Shipping API Reference](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference) — there is no public `dev.wix.com` docs page for them, so that file is the authoritative spec. The recipes below link to it where needed. + +### Actions — set up shipping + +> - [Set up shipping rates / rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-rates) — tags: `[intent:setup-rates]` · priority 0 +> - [Set up delivery regions / coverage](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-regions) — tags: `[intent:setup-regions]` · priority 0 +> - [Set up store pickup / local delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-pickup-local-delivery) — tags: `[intent:setup-pickup]` · priority 0 +> - [Add free shipping over $X](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-add-free-shipping) — tags: `[intent:free-shipping]` · priority 0 + +### Optimize & fix + +> - [Optimize shipping rates (flat ↔ tiered, gaps)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-optimize-rates) — tags: `[intent:optimize-rates]` · priority 0 +> - [Fix coverage gaps (regions with no shipping option)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-fix-coverage-gaps) — tags: `[intent:fix-coverage]` · priority 0 + +### Troubleshoot + +> - [Shipping rate incorrect (customer charged wrong shipping)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-optimize-rates) — tags: `[intent:rate-incorrect]` · priority 0 · *audit rates via the Rate Pricing Sanity guardrail, then correct the rate structure* + +### Fulfillment handoff + +> - Mark orders fulfilled, update tracking, partial/bulk fulfill, find unshipped orders, print invoices, or export shipping labels — tags: `[intent:fulfill-order]`, `[intent:update-tracking]`, `[intent:find-unshipped]`, `[intent:shipping-labels]` · **see [Fulfillment](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/fulfillment)** + +## Tag matching + +The agent matches the merchant's natural-language query to an `intent:*` tag (cues are in each file's `description`), AND matches MerchantContext to any context tags (e.g. `country`, `region`). All of an entry's tags must be satisfied for it to be eligible; highest tag-count wins; ties → `priority`. + +### Worked examples + +| Merchant query | MerchantContext | Match | +|---|---|---| +| "Set up free shipping over $50" | any | `ecom-shipping-free-shipping` via `[intent:free-shipping]` | +| "How much should I charge for shipping?" | any | `ecom-shipping-setup-rates` via `[intent:setup-rates]` | +| "I want customers to pick up from my shop" | any | `ecom-shipping-setup-pickup` via `[intent:setup-pickup]` | +| "Some regions have no shipping option" | any | `ecom-shipping-fix-coverage` via `[intent:fix-coverage]` | +| "A customer was charged the wrong shipping" | any | `ecom-shipping-optimize-rates` via `[intent:rate-incorrect]` (runs rate-sanity guardrail first) | + +## Base recipe (fallback) + +If nothing matches, the merchant's intent is unclear. Ask **one** clarifying question: + +> "Do you want to **set up** shipping (rates, regions, or pickup), **add free shipping**, **optimize** your existing rates, or **fix** a region with no shipping option?" + +Map the answer to one of the `intent:*` tags above and re-dispatch. Order-fulfillment requests belong to **Fulfillment**. diff --git a/skills/wix-manage/references/ecommerce/ecom-tax.md b/skills/wix-manage/references/ecommerce/ecom-tax.md new file mode 100644 index 00000000..3c028b9f --- /dev/null +++ b/skills/wix-manage/references/ecommerce/ecom-tax.md @@ -0,0 +1,47 @@ +--- +name: "Tax" +description: Tax configuration for an eCommerce site — calculator choice (Wix Manual vs Avalara), tax regions, tax groups, inclusive/exclusive pricing, EU VAT, and tax-calculation troubleshooting. +--- + +# Tax + +Set up and manage how your store calculates and collects tax — what calculator to use, which regions to cover, how rates apply to products, and how to diagnose wrong tax on orders. + +**Tax is NOT:** +- Invoicing / order tax breakdowns → see **Orders**. +- Product pricing or VAT-inclusive display in product listings → see **Catalog**. +- Country availability for shipping → see **Shipping & fulfillment**. + +> **Before dispatching** — confirm MerchantContext is loaded. If `siteData.country` is not in your conversation context, load it via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context). Skip if already loaded. +> +> **Promotion dispatch.** Score each entry below by (a) the merchant's query → `intent:*` tags, (b) MerchantContext → context tags. Load the **highest-scoring** entry. Ties → highest `priority`. No match → follow the base recipe at the bottom. +> +> - [Configure tax (Avalara)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/tax-configure-avalara) — tags: `[intent:configure, calculator:AVALARA]` · priority 1 +> - [Configure tax (EU VAT)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/tax-configure-eu-vat) — tags: `[intent:configure, region:EU]` · priority 1 +> - [Configure tax (Wix Manual)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/tax-configure-wix-manual) — tags: `[intent:configure]` · priority 0 +> - [Switch tax calculator](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/tax-switch-calculator) — tags: `[intent:switch-calculator]` · priority 0 +> - [Audit tax setup](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/tax-audit-setup) — tags: `[intent:audit]` · priority 0 +> - [Tax calculation wrong](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/tax-calculation-wrong) — tags: `[intent:troubleshoot]` · priority 0 + +## Tag matching + +The agent matches the merchant's natural-language query to an `intent:*` tag (per the keyword cues each promotion file lists in its `description`), AND matches MerchantContext to any context tags. A promotion's tags must ALL be satisfied for it to be eligible. Among eligible promotions, the one with the highest tag-count wins; ties broken by `priority`. + +### Worked examples + +| Merchant query | MerchantContext | Match | +|---|---|---| +| "Set up VAT for Germany" | `country: DE` → `region: EU` | `ecom-tax-eu-vat` (2 tags matched) | +| "Configure tax for my US store" | `country: US`, `calculator: WIX_MANUAL` | `ecom-tax-configure` (1 tag) | +| "Set up Avalara" | `country: US`, `calculator: WIX_MANUAL` | `ecom-tax-avalara` (1 tag: `intent:configure`; the `calculator:AVALARA` tag is intentionally NOT matched because the merchant is ABOUT to switch — they don't have it yet. Avalara wins on intent + priority 1.) | +| "Audit my taxes" | any | `ecom-tax-audit` | +| "Tax on order #1234 is wrong" | any | `ecom-tax-troubleshoot-calc-wrong` | +| "Switch to Avalara" | any | `ecom-tax-switch-calculator` | + +## Base recipe (fallback) + +If no promotion matches, the merchant's intent is unclear. Ask **one** clarifying question: + +> "Do you want to **set up tax** for the first time, **change** your current calculator (e.g. switch to Avalara), **review** your existing setup, or **fix** a wrong tax amount on an order?" + +Map the answer to one of the four `intent:*` tags and re-dispatch. diff --git a/skills/wix-manage/references/ecommerce/fulfillment/ecom-fulfillment-bulk-fulfill-orders.md b/skills/wix-manage/references/ecommerce/fulfillment/ecom-fulfillment-bulk-fulfill-orders.md new file mode 100644 index 00000000..b21453ca --- /dev/null +++ b/skills/wix-manage/references/ecommerce/fulfillment/ecom-fulfillment-bulk-fulfill-orders.md @@ -0,0 +1,78 @@ +--- +name: "Fulfillment: Bulk Fulfill Orders" +description: Bulk-fulfills many eCommerce orders safely using the Order Fulfillments bulk create endpoint. Covers finding eligible orders, building batches, including tracking, handling partial failures, and retrying only failed orders. +--- + +# Bulk Fulfill Orders + +Use this when the merchant wants to fulfill many orders at once, such as all paid unshipped orders from today. + +Bulk fulfillment is a batch mutation. Be careful about order selection, duplicate fulfillment, and partial failures. + +## Required APIs + +- Search orders: `POST https://www.wixapis.com/ecom/v1/orders/search` +- Bulk create fulfillments: `POST https://www.wixapis.com/ecom/v1/fulfillments/orders/bulk/create-fulfillments` +- List fulfillments for a single order when checking duplicates: `GET https://www.wixapis.com/ecom/v1/fulfillments/orders/{orderId}` +- List fulfillments for multiple orders when prechecking a batch: `POST https://www.wixapis.com/ecom/v1/fulfillments/list-by-ids` + +## API constraints from public docs + +- Fulfillments can only be created for approved orders. +- Bulk create supports up to 100 orders at a time. +- Each fulfillment can include up to 300 line items. +- Each order line item can be included in only one fulfillment. +- Predefined carriers can auto-generate tracking links; custom carriers need manual tracking links. + +## Step 1: Select eligible orders + +Start from an explicit merchant selection or query for orders that are ready to ship. + +Common filters: + +- payment status is paid +- fulfillment status is `NOT_FULFILLED` or the specific status requested +- order status is approved +- order date or promised ship date matches the merchant's batch + +Do not include unpaid orders unless the merchant explicitly confirms fulfillment before payment. + +## Step 2: Build the batch payload + +`bulk/create-fulfillments` takes `ordersWithFulfillments`, one entry per order. Each entry should include the line items and quantities to fulfill, plus optional tracking info. + +Use per-order tracking when available. If tracking is not available yet, confirm whether the merchant still wants to mark the orders fulfilled. + +## Step 3: Submit in safe batches + +For large batches: + +1. Chunk the orders into groups of at most 100 orders. +2. Submit one chunk at a time. +3. Record per-order success or failure. +4. Retry only failed orders after inspecting the error. + +## Step 4: Handle partial failures + +Do not rerun the whole batch blindly. That can duplicate successful fulfillments. + +For each failed order: + +- inspect the error +- check existing fulfillments for that order +- retry only if the order still needs fulfillment +- report failures separately from successes + +## Guardrails + +- Confirm the merchant's selection before mutating many orders. +- Confirm whether orders without tracking should still be marked fulfilled. +- Avoid fulfilling unpaid orders by default. +- Avoid fulfilling non-approved orders. +- Avoid duplicate line-item fulfillment. +- Preserve partial-fulfillment quantities exactly. +- Keep a summary of successes, failures, and skipped orders. + +## Audit note + +This file is not redundant with the Bulk Create Fulfillments API docs because it adds safe order selection, paid/approved-order filters, duplicate prechecks, batch chunking, partial-failure retry rules, and merchant confirmation for a high-impact batch mutation. diff --git a/skills/wix-manage/references/ecommerce/fulfillment/ecom-fulfillment-fulfill-orders.md b/skills/wix-manage/references/ecommerce/fulfillment/ecom-fulfillment-fulfill-orders.md new file mode 100644 index 00000000..360344c3 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/fulfillment/ecom-fulfillment-fulfill-orders.md @@ -0,0 +1,106 @@ +--- +name: "Fulfillment: Fulfill Orders & Tracking" +description: Fulfill orders and manage tracking - mark an order fulfilled, add/update tracking, fulfill part of an order, and avoid duplicate fulfillments. Uses the eCommerce Order Fulfillments API. +--- + +# Fulfill Orders & Tracking + +Create and manage order fulfillments via the **Order Fulfillments API** (TPA-public / GA). A fulfillment records that some or all of an order's line items shipped, optionally with carrier and tracking. + +## Required APIs + +- Create: `POST https://www.wixapis.com/ecom/v1/fulfillments/orders/{orderId}/create-fulfillment` +- Update: `PATCH https://www.wixapis.com/ecom/v1/fulfillments/{fulfillmentId}/orders/{orderId}` +- List for an order: `GET https://www.wixapis.com/ecom/v1/fulfillments/orders/{orderId}` +- Search/get order first when the merchant provides an order number instead of an order ID. + +For many orders at once, use [Bulk Fulfill Orders](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/fulfillment-bulk-fulfill-orders). + +## API constraints from public docs + +- Fulfillments can only be created for orders in an approved state. +- Each order line item can be included in only one fulfillment. +- A single fulfillment can include up to 300 line items. +- Standard shipping providers can auto-generate tracking links from provider + tracking number. +- Custom shipping providers require a manually supplied tracking link. + +## Mark an order fulfilled + +First get/search the order and confirm it is approved and eligible for fulfillment. Then call `create-fulfillment` with the order line items that shipped. To include tracking, add `trackingInfo`: + +```json +{ + "fulfillment": { + "lineItems": [ + { + "id": "", + "quantity": 2 + } + ], + "trackingInfo": { + "trackingNumber": "1Z999...", + "shippingProvider": "ups", + "trackingLink": "https://www.ups.com/track?tracknum=1Z999..." + } + } +} +``` + +The response returns the created `fulfillment.id`. The order's fulfillment status moves toward `FULFILLED`. + +## Add or update tracking on an existing fulfillment + +If the order is already fulfilled and the merchant only needs to add or correct tracking, update the existing fulfillment instead of creating another one. + +1. Get the fulfillment ID: + +```http +GET https://www.wixapis.com/ecom/v1/fulfillments/orders/{orderId} +``` + +2. Patch the fulfillment: + +```http +PATCH https://www.wixapis.com/ecom/v1/fulfillments/{fulfillmentId}/orders/{orderId} +``` + +Example body: + +```json +{ + "fulfillment": { + "id": "", + "trackingInfo": { + "trackingNumber": "1Z999...", + "shippingProvider": "ups" + } + } +} +``` + +## Partial fulfillment + +For "ship some items now", create a fulfillment with only the line items and quantities shipping now. The order becomes `PARTIALLY_FULFILLED`; create another fulfillment later for the remaining items. + +Each shipment can carry its own tracking number. + +## Response handling + +Create Fulfillment returns the created `fulfillmentId` and `orderWithFulfillments`. Update/List return `orderWithFulfillments`. Use these response fields to verify: + +- the target line items and quantities are included +- the tracking info is present +- the order moved to the expected fulfillment state + +## Guardrails + +- Only fulfill paid orders unless the merchant explicitly confirms fulfillment before payment. +- Only create fulfillment for an approved order. +- Do not re-fulfill already-fulfilled line items. Check existing fulfillments first. +- Match `quantity` to what actually shipped so partial states stay accurate. +- If the API returns `TRACKING_NUMBER_ALREADY_EXISTS`, reuse or update the existing fulfillment instead of creating a duplicate. +- Do not use fulfillment to cancel an order, process a refund, or buy/export a shipping label. + +## Audit note + +This file is not redundant with the Order Fulfillments API docs because it adds merchant-language routing, order-number lookup, paid/approved-order checks, duplicate-fulfillment prevention, partial quantity handling, tracking update branching, and post-write verification. diff --git a/skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md b/skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md deleted file mode 100644 index 2a215203..00000000 --- a/skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md +++ /dev/null @@ -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) diff --git a/skills/wix-manage/references/ecommerce/guardrail-margin-protection.md b/skills/wix-manage/references/ecommerce/guardrail-margin-protection.md deleted file mode 100644 index adf5854a..00000000 --- a/skills/wix-manage/references/ecommerce/guardrail-margin-protection.md +++ /dev/null @@ -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 | diff --git a/skills/wix-manage/references/ecommerce/guardrail-rate-pricing-sanity.md b/skills/wix-manage/references/ecommerce/guardrail-rate-pricing-sanity.md deleted file mode 100644 index 408494a1..00000000 --- a/skills/wix-manage/references/ecommerce/guardrail-rate-pricing-sanity.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -name: "Guardrail: Rate Pricing Sanity" -description: Validates shipping rate pricing against AOV and catalog data. Flags excessive rates, per-item penalties, unreachable free shipping thresholds, and backup rate sticker shock. -layer: guardrail ---- -# Guardrail: Rate Pricing Sanity - -## When to use - -Run these checks when evaluating existing shipping rates or before creating/updating shipping rate configurations. All thresholds are relative to the store's Average Order Value (AOV). - ---- - -## Check 1: Excessive shipping cost - -**Threshold**: Any rate `amount` > AOV x 0.15 (15%) - -**Why**: Shipping costs above 15% of order value are a top reason for cart abandonment. Customers who see disproportionately high shipping fees frequently abandon their carts. - -**Detection**: -- For each shipping rate, compare `amount` against `AOV × 0.15` -- If exceeded → flag: - -> "Shipping rate '{title}' charges ${amount}, which is {pct}% of your average order value (${AOV}). Shipping costs above 15% of order value are a top reason for cart abandonment." - ---- - -## Check 2: Per-item penalty (multiplyByQuantity) - -**Trigger**: `multiplyByQuantity: true` on any shipping rate - -**Why**: Per-item shipping charges penalize larger orders and discourage customers from adding more items to cart. - -**Detection**: -- Find all rates with `multiplyByQuantity: true` -- Calculate the impact for a typical multi-item order: - -> "Your '{title}' rate charges per item (${amount} x quantity). A 5-item order costs ${amount x 5}. Switch to a flat rate or tiered pricing to encourage larger orders." - ---- - -## Check 3: Free shipping threshold too high - -**Threshold**: Free shipping threshold > AOV x 2 - -**Why**: If the free shipping minimum is more than double the average order, very few customers will ever qualify. The threshold should be achievable — close enough to the AOV to encourage customers to add one more item. - -**Detection**: -- Compare free shipping `threshold` against `AOV × 2` -- If exceeded → flag: - -> "Your free shipping threshold (${threshold}) is {X}x your average order (${AOV}). Most customers won't reach it. Lower to ${AOV x 1.2} to make it achievable and drive larger orders." - ---- - -## Check 4: Free shipping threshold too low - -**Threshold**: Free shipping threshold < AOV x 0.8 - -**Why**: If the threshold is below the average order value, most customers already qualify for free shipping without adding anything to their cart. This provides no upsell incentive and may erode margins unnecessarily. - -**Detection**: -- Compare free shipping `threshold` against `AOV × 0.8` -- If below → flag: - -> "Your free shipping threshold (${threshold}) is below your average order value (${AOV}). Most customers already qualify, so this threshold isn't driving larger orders. Consider raising it to ${AOV x 1.2} to encourage add-on purchases." - ---- - -## Check 5: Backup rate sticker shock - -**Threshold**: `backupRate.amount` > effective AOV x 0.15 - -**Why**: Backup rates apply when the primary carrier can't fulfill (e.g., remote address, service outage). If the backup rate is dramatically higher than normal shipping, customers experience sticker shock at checkout. - -**Detection**: -- For each carrier's `backupRate`, compare `amount` against `effective_aov × 0.15` -- If exceeded → flag: - -> "Backup rate of ${amount} is {pct}% of your average order value. When triggered, this will surprise customers with unexpectedly high shipping. Set the backup rate to 5-10% of average order value (${effective_aov x 0.05} - ${effective_aov x 0.10})." - ---- - -## Check 6: Hidden surcharges - -**Threshold**: Total `additionalCharges` across all carriers > AOV x 0.10 - -**Why**: Carrier surcharges (fuel, residential delivery, handling fees) add up. If the total surcharge burden exceeds 10% of the order value, it may negate the perceived value of the base shipping rate. - -**Detection**: -- Sum all `additionalCharges` across active carriers -- Compare total against `AOV × 0.10` -- If exceeded → flag: - -> "Carrier surcharges add ${total} to shipping costs. Combined with base rates, total shipping cost may deter customers. Review each surcharge to determine if it's necessary." - ---- - -## Summary: Pricing sanity thresholds - -| Check | Threshold | Action | -|---|---|---| -| Excessive rate | Rate > 15% of AOV | Flag — cart abandonment risk | -| Per-item penalty | `multiplyByQuantity: true` | Flag — discourages larger orders | -| Free threshold too high | Threshold > 2x AOV | Flag — unreachable for most customers | -| Free threshold too low | Threshold < 0.8x AOV | Flag — no upsell incentive, margin erosion | -| Backup rate shock | Backup > 15% of AOV | Flag — recommend 5-10% of AOV | -| Hidden surcharges | Total surcharges > 10% of AOV | Flag — review necessity | diff --git a/skills/wix-manage/references/ecommerce/guardrail-shipping-health.md b/skills/wix-manage/references/ecommerce/guardrail-shipping-health.md deleted file mode 100644 index 0f76952b..00000000 --- a/skills/wix-manage/references/ecommerce/guardrail-shipping-health.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -name: "Guardrail: Shipping Health" -description: Shipping health score calculation (CRITICAL/POOR/FAIR/GOOD/EXCELLENT) with exact scoring criteria. Includes the mandatory business context filter for international shipping recommendations. -layer: guardrail -references: - - name: "Troubleshoot: Checkout Delivery Drop-off" - path: ecommerce/troubleshoot-checkout-delivery-dropoff.md - load: false ---- -# Guardrail: Shipping Health - -> **Related skills**: -> - [Troubleshoot: Checkout Delivery Drop-off](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/troubleshoot-checkout-delivery-dropoff) - -## When to use - -Calculate the shipping health score whenever evaluating a store's shipping configuration. Use this score to prioritize recommendations and determine urgency of shipping issues. - ---- - -## Health score levels - -### CRITICAL - -Any of the following conditions: - -- `delivery_profiles` is empty AND `shipping_options` is empty -- All regions across all profiles have `active: false` - -**Implication**: The store cannot ship any orders. Immediate action required. - -### POOR - -Any of the following conditions: - -- Only 1 delivery profile with empty regions -- Only 1 shipping option total -- `delivery_step_cvr` < 50% with shipping issues detected -- All carriers have `backupRate.active: false` - -**Implication**: Shipping is minimally functional but has significant gaps that are likely causing lost sales. - -### FAIR - -All of the following conditions: - -- 1-2 delivery profiles with 1-2 active regions -- 2-4 shipping options -- No free shipping option available -- OR: `delivery_step_cvr` between 50-65% - -**Implication**: Basic shipping is working but missing key elements that drive conversion. - -### GOOD - -All of the following conditions: - -- 1+ delivery profiles with both domestic and international regions -- 3-5 shipping options including at least one free shipping option -- 1+ active carriers -- `delivery_step_cvr` between 65-75% - -**Implication**: Solid shipping setup. Optimization opportunities exist but fundamentals are covered. - -### EXCELLENT - -All of the following conditions: - -- Multiple active regions -- Tiered shipping rates -- Free shipping option available -- Multiple carriers with backup rates enabled -- Pickup and/or local delivery options configured -- `delivery_step_cvr` ≥ 75% -- No `multiplyByQuantity` pricing on any rate - -**Implication**: Best-in-class shipping configuration. Focus on maintaining and fine-tuning. - ---- - -## Business context filter (MANDATORY) - -**This filter MUST be applied before recommending any international shipping action.** - -### Check business type - -Inspect the store's `industry` and `businessType` fields (case-insensitive match) for any of the following keywords: - -- food -- restaurant -- grocery -- bakery -- catering -- perishable -- fresh -- meat -- produce -- dairy -- drink -- beverage - -### If matched - -**DO NOT recommend any international shipping action.** Perishable/food businesses face regulatory, spoilage, and logistics barriers that make international shipping impractical as a default recommendation. - -### Identifying international regions - -A region is considered "international" if any of the following are true: - -- Region `name` contains "international" or "internacional" (case-insensitive) -- Region `destinations[]` is empty (wildcard / all countries) -- Region `destinations` include countries outside the store's home country - ---- - -## Summary: Score decision table - -| Score | Key indicator | Action | -|---|---|---| -| CRITICAL | No profiles/options or all regions inactive | Immediate setup required | -| POOR | Minimal config, low CVR, or no backup rates | Address fundamental gaps | -| FAIR | Basic setup, no free shipping, moderate CVR | Add free shipping, expand regions | -| GOOD | Domestic + international, free shipping, good CVR | Optimize rates and carriers | -| EXCELLENT | Full coverage, tiered rates, high CVR | Maintain and fine-tune | diff --git a/skills/wix-manage/references/ecommerce/orders/ecom-orders-cancel-order.md b/skills/wix-manage/references/ecommerce/orders/ecom-orders-cancel-order.md new file mode 100644 index 00000000..9e27d660 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/orders/ecom-orders-cancel-order.md @@ -0,0 +1,84 @@ +--- +name: "Orders: Cancel Order" +description: Cancels an eCommerce order safely using the Orders Cancel API. Covers order lookup, cancellation eligibility, restock/email options, confirmation, and post-cancel verification. +--- + +# Cancel Order + +Use this when the merchant explicitly wants to cancel an eCommerce order. + +Canceling is final for the order lifecycle. Do not call the cancel endpoint before confirming the exact order and side effects. + +## Required API + +- [Cancel Order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/cancel-order): `POST https://www.wixapis.com/ecom/v1/orders/{id}/cancel` +- Permission: `Manage Orders` +- Optional body fields include `restockAllItems`, `sendOrderCanceledEmail`, and `customMessage`. + +## Step 1: Resolve and inspect the order + +If the merchant gives an order number such as `#1053`, search orders first to resolve the canonical order ID. Then get the order and inspect: + +- order ID and number +- customer/buyer +- current order `status` +- `paymentStatus` +- `fulfillmentStatus` +- line items and Wix Stores inventory relevance + +Do not cancel if multiple orders match. Ask one clarifying question. + +## Step 2: Clarify side effects + +Before cancellation, confirm: + +- whether to restock all Wix Stores items +- whether to send the buyer an order-canceled email +- custom message, if any +- whether a refund is also needed + +Cancellation is not the same as refunding. If the merchant also wants money returned, route the refund portion to verified Get Paid/payment docs or Dashboard guidance. + +## Step 3: Confirm before mutation + +Ask for explicit confirmation: + +> "Confirm canceling order {orderNumber}/{orderId}, restockAllItems={true/false}, sendOrderCanceledEmail={true/false}?" + +Do not proceed on vague confirmation if the order or side effects are ambiguous. + +## Step 4: Cancel + +```http +POST https://www.wixapis.com/ecom/v1/orders/{id}/cancel +``` + +Example body: + +```json +{ + "restockAllItems": true, + "sendOrderCanceledEmail": true, + "customMessage": "Your order was canceled per your request." +} +``` + +## Step 5: Verify + +After cancellation, get the order again or inspect the response order and report: + +- status is `CANCELED` +- whether restock/email were requested +- whether refund/payment action is still needed +- any failure/error message if cancellation did not complete + +## Guardrails + +- Do not cancel orders that are already canceled/rejected without reporting current state. +- Do not treat cancellation as refund. +- Do not route cancel-order to Fulfillment; fulfillment cancellation and order cancellation are different operations. +- If the order is fulfilled or partially fulfilled, call out the shipping/return implications before canceling. + +## Audit note + +This file is not redundant with the API docs because it adds order-number resolution, side-effect confirmation, cancellation-vs-refund separation, and post-cancel verification. diff --git a/skills/wix-manage/references/ecommerce/setup-coupons.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-create-coupon.md similarity index 89% rename from skills/wix-manage/references/ecommerce/setup-coupons.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-create-coupon.md index ee1651cb..6662f76b 100644 --- a/skills/wix-manage/references/ecommerce/setup-coupons.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-create-coupon.md @@ -1,5 +1,5 @@ --- -name: "Setup: Coupons" +name: "Pricing: Create Coupon" description: Creates and manages coupon codes using the Coupons V2 API. Covers coupon types (percentage, fixed amount, fixed price, free shipping), scope targeting, usage limits, and the mapping from discount recommendations to coupon API payloads. layer: config --- @@ -22,7 +22,7 @@ layer: config Before creating a coupon, check for code conflicts and existing promotions on the same scope. -**Endpoint**: `POST https://www.wixapis.com/v2/coupons/query` +**Endpoint**: `POST https://www.wixapis.com/stores/v2/coupons/query` **Request**: ```json @@ -66,11 +66,21 @@ Before creating a coupon, check for code conflicts and existing promotions on th Check for: duplicate codes, overlapping scopes with active coupons, and cross-mechanism stacking with active automatic discount rules. +### Guardrails — run before creating the coupon + +- **Duplicate / conflicting code** — reject a code already in use. +- **Cross-mechanism stacking** — coupons stack with automatic discount rules at checkout. Query active discount rules on overlapping scope; if found, warn with the combined effective discount ("a 20% coupon during a 20% automatic sale = ~36% off"). Only one coupon applies per checkout, but automatic rules are unlimited. +- **% sanity** — > 50% warn (show a $100 → $(100−pct) example); = 100% block unless confirmed; > 100% always block. +- **Margin** — if cost data is available, ensure the discount doesn't push price below cost; otherwise warn for > 40%. +- **User override** — explicit merchant values override these caps; document the override in your reasoning. + +(The automatic-rule side of these checks lives in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails".) + --- ## Step 2: Create a percentage-off coupon -**Endpoint**: `POST https://www.wixapis.com/v2/coupons` +**Endpoint**: `POST https://www.wixapis.com/stores/v2/coupons` **Request** — 15% off all store products: ```json diff --git a/skills/wix-manage/references/ecommerce/setup-discount-rules.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-create-discount-rule.md similarity index 87% rename from skills/wix-manage/references/ecommerce/setup-discount-rules.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-create-discount-rule.md index 26449345..82219aa0 100644 --- a/skills/wix-manage/references/ecommerce/setup-discount-rules.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-create-discount-rule.md @@ -1,5 +1,5 @@ --- -name: "Setup: Discount Rules" +name: "Pricing: Create Discount Rule" description: Configures automatic discount rules using the eCommerce Discount Rules API. Covers percentage and fixed-amount discounts, scope targeting (catalog-wide, specific collections, or individual products), scheduling active periods, and the find-by-name + update pattern. layer: config --- @@ -126,6 +126,36 @@ Note existing rules and their scopes to avoid stacking conflicts. --- +## Guardrails — run before creating or updating any discount + +These checks guard every discount creation (rule **or** coupon). Run them before the create/update calls below. **User input overrides all caps** — if the merchant explicitly asks for a value beyond a threshold, honor it and document the override in your reasoning. + +**Conflict / stacking** (uses the Step 1 query of active rules; for coupons, also query active coupons): +- **Same-scope overlap** — a new rule conflicts with an existing active rule when scopes overlap (both `CATALOG`; `CATALOG` vs `COLLECTION`; same `COLLECTION`/`SPECIFIC_PRODUCTS` id). Wix stacks automatic rules → warn and offer to deactivate the existing one. +- **Time overlap** — overlapping `activeTimeInfo` on the same scope (`existingStart < newEnd AND existingEnd > newStart`) → warn about the overlap window. +- **Cross-mechanism (automatic + coupon)** — automatic discounts and coupons both apply at checkout. If creating a rule, query active coupons on overlapping scope (and vice-versa); warn with the combined effective discount. (Only one coupon per checkout, but automatic rules are unlimited.) + +**Margin / sanity:** +- **Global cap** — default max discount **25%**; flag anything higher (proceed only on explicit request). +- **Minimum margin** — default floor **15%**; if cost data is available, `effective_margin = (price − cost − discount_amount) / price × 100` must stay ≥ 15% (block + explain otherwise). +- **% sanity** — > 50% warn (show a $100 → $(100−pct) example); = 100% block unless confirmed ("makes the product free"); > 100% always block. +- **Stacking margin** — when a new discount overlaps existing active ones, evaluate the *combined* discount against the cap and margin floor, not just the new one in isolation. + +| Scenario | Action | +|---|---| +| Discount ≤ 25% and margin ≥ 15%, no scope overlap | Proceed | +| Scope/time/cross-mechanism overlap | Warn; offer to deactivate existing or confirm stacking | +| Discount 26–50% (no override) | Warn, ask to confirm | +| Discount > 50% | Warn with $ example, confirm | +| Discount = 100% | Block unless confirmed | +| Discount > 100% | Block always | +| Combined/stacked discount exceeds cap or margin floor | Warn about cumulative effect | +| Any threshold, explicit user override | Proceed, document the override in reasoning | + +When a discount *isn't* applying as expected, see [Troubleshoot: Discount Not Applying](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-discount-not-applying). + +--- + ## Step 2: Create a percentage discount rule **Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules` diff --git a/skills/wix-manage/references/ecommerce/flow-bundle-and-save.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-bundle-and-save.md similarity index 87% rename from skills/wix-manage/references/ecommerce/flow-bundle-and-save.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-bundle-and-save.md index 5173d917..49a17d60 100644 --- a/skills/wix-manage/references/ecommerce/flow-bundle-and-save.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-bundle-and-save.md @@ -1,20 +1,10 @@ --- name: "Flow: Bundle and Save" description: Creates a discount campaign promoting product discovery and cross-selling by requiring minimum item quantities. Targets high-margin categories with complementary products. -layer: flow -references: - - name: "Guardrail: Discount Conflicts" - path: ecommerce/guardrail-discount-conflicts.md - load: true - - name: "Setup: Discount Rules" - path: ecommerce/setup-discount-rules.md - load: true --- # Flow: Bundle & Save Campaign -> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`: -> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-discount-conflicts) -> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-discount-rules) +> **Before executing this skill**, read [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) with `ReadFullDocsArticle` — it contains the discount-rule mechanics **and** the pre-create guardrails (conflict/stacking, margin floor, %-sanity). Creates a discount that rewards customers for purchasing multiple items, encouraging product discovery and cross-selling. The discount activates when the cart contains a minimum number of items, and targets categories or products where bundling makes strategic sense. @@ -118,29 +108,7 @@ If scope is CATEGORY, call `getCategoryIds` to convert category names to GUIDs. ## Step 7: Run guardrail checks -**Run the Guardrail: Discount Conflicts checks before creating the rule.** - -1. Query existing active discount rules: - -**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query` - -**Request**: -```json -{ - "query": { - "filter": { - "active": true - }, - "paging": { - "limit": 100 - } - } -} -``` - -2. Check for scope overlap with existing rules. Bundle discounts are especially prone to stacking — a customer buying 3 items in a category with both a bundle discount and a catalog-wide sale would get both. -3. Check for coupon stacking risks. -4. If conflicts found, present to merchant and get confirmation. +**Run the pre-create guardrails in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails" before creating the rule.** Bundle discounts are especially prone to **scope-overlap stacking** (a customer buying 3 items in a category with both a bundle discount and a catalog-wide sale gets both) and **coupon stacking** — present any conflicts to the merchant and confirm. --- diff --git a/skills/wix-manage/references/ecommerce/flow-seasonal-promotion.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-seasonal-promotion.md similarity index 88% rename from skills/wix-manage/references/ecommerce/flow-seasonal-promotion.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-seasonal-promotion.md index 07c3246f..81afdd12 100644 --- a/skills/wix-manage/references/ecommerce/flow-seasonal-promotion.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-seasonal-promotion.md @@ -1,20 +1,10 @@ --- name: "Flow: Seasonal Promotion" description: Creates event-driven promotional campaigns tied to holidays or seasonal events. Uses country and date context to identify upcoming events, calculates optimal campaign windows, and targets relevant categories. -layer: flow -references: - - name: "Guardrail: Discount Conflicts" - path: ecommerce/guardrail-discount-conflicts.md - load: true - - name: "Setup: Discount Rules" - path: ecommerce/setup-discount-rules.md - load: true --- # Flow: Seasonal Promotion -> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`: -> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-discount-conflicts) -> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-discount-rules) +> **Before executing this skill**, read [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) with `ReadFullDocsArticle` — it contains the discount-rule mechanics **and** the pre-create guardrails (conflict/stacking, margin floor, %-sanity). Creates event-driven promotional discounts tied to holidays, shopping events, or seasonal milestones. The flow identifies upcoming events based on the site's country and current date, calculates optimal campaign start/end windows, and targets event-relevant product categories with appropriately sized discounts. @@ -160,30 +150,7 @@ If scope is CATEGORY, call `getCategoryIds` to convert category names to GUIDs. ## Step 8: Run guardrail checks -**Run the Guardrail: Discount Conflicts checks before creating the rule.** - -1. Query existing active discount rules: - -**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query` - -**Request**: -```json -{ - "query": { - "filter": { - "active": true - }, - "paging": { - "limit": 100 - } - } -} -``` - -2. Check for time overlap — seasonal promotions have defined windows, so check that no existing rule covers the same period on the same scope. -3. Check for scope overlap — a seasonal category discount stacking with an existing catalog-wide discount could create unexpectedly deep combined discounts. -4. Check for coupon stacking — seasonal events often have high coupon usage. -5. If conflicts found, present to merchant and get confirmation. +**Run the pre-create guardrails in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails" before creating the rule.** For seasonal campaigns the most relevant are **time overlap** (defined windows — ensure no existing rule covers the same period/scope), **scope overlap** (a category discount stacking with a catalog-wide one), and **coupon stacking** (seasonal events drive high coupon usage). Present any conflicts to the merchant and get confirmation. --- diff --git a/skills/wix-manage/references/ecommerce/flow-stock-mover.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-stock-mover.md similarity index 81% rename from skills/wix-manage/references/ecommerce/flow-stock-mover.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-stock-mover.md index 1bcb9ab1..2032b8a5 100644 --- a/skills/wix-manage/references/ecommerce/flow-stock-mover.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-stock-mover.md @@ -1,24 +1,10 @@ --- name: "Flow: Stock Mover" description: Creates discount campaigns to clear slow-moving inventory by targeting products with high stock levels and low sales velocity. Uses deeper discounts proportional to inventory urgency. -layer: flow -references: - - name: "Guardrail: Discount Conflicts" - path: ecommerce/guardrail-discount-conflicts.md - load: true - - name: "Guardrail: Margin Protection" - path: ecommerce/guardrail-margin-protection.md - load: true - - name: "Setup: Discount Rules" - path: ecommerce/setup-discount-rules.md - load: true --- # Flow: Stock Mover Clearance -> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`: -> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-discount-conflicts) -> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-margin-protection) -> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-discount-rules) +> **Before executing this skill**, read [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) with `ReadFullDocsArticle` — it contains the discount-rule mechanics **and** the pre-create guardrails (conflict/stacking, margin floor, %-sanity). Creates a discount targeting slow-moving inventory — products with high stock levels and low sales velocity. The discount depth is proportional to how overstocked the product is, with deeper discounts for the most stagnant items. Margin protection guardrails are especially important here since clearance discounts tend to push closer to cost. @@ -122,38 +108,7 @@ If scope is CATEGORY, call `getCategoryIds` to convert category names to GUIDs. ## Step 6: Run guardrail checks -**IMPORTANT: Run both guardrail checks before creating the discount rule. Clearance discounts are the most likely to trigger margin warnings.** - -### 6a: Discount Conflicts - -1. Query existing active discount rules: - -**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query` - -**Request**: -```json -{ - "query": { - "filter": { - "active": true - }, - "paging": { - "limit": 100 - } - } -} -``` - -2. Check for scope overlap. Clearance items that already have an active discount would stack — warn the merchant about combined discount depth. -3. Check for coupon stacking risks. A customer combining a clearance discount with a coupon code could get an unexpectedly deep total discount. - -### 6b: Margin Protection - -This check is especially critical for clearance: - -- Verify `discount_percentage <= avg_profit_margin - 15%` for each candidate product. -- If the discount would push effective margin below 15%, warn the merchant: "This clearance discount of {discount}% on {product_name} would reduce the effective margin to {remaining_margin}%. The minimum margin threshold is 15%. Proceed?" -- If margin data is unavailable, apply extra caution — cap at 15% unless the merchant explicitly overrides. +**Run the pre-create guardrails in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails" before creating the rule** (conflict/stacking, %-sanity, margin floor). Clearance is the **most margin-sensitive** case: discounts push closest to cost, so the margin-floor check (effective margin ≥ 15% unless the merchant overrides) is the one most likely to fire here — verify it per candidate product. --- diff --git a/skills/wix-manage/references/ecommerce/flow-upsell-boost.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-upsell-boost.md similarity index 81% rename from skills/wix-manage/references/ecommerce/flow-upsell-boost.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-upsell-boost.md index c599b635..b021481f 100644 --- a/skills/wix-manage/references/ecommerce/flow-upsell-boost.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-upsell-boost.md @@ -1,24 +1,10 @@ --- name: "Flow: Upsell Boost" description: Creates a discount campaign to increase average order value by setting minimum subtotal conditions above current AOV. Uses margin-based discount tiers and targets high-margin categories. -layer: flow -references: - - name: "Guardrail: Discount Conflicts" - path: ecommerce/guardrail-discount-conflicts.md - load: true - - name: "Guardrail: Margin Protection" - path: ecommerce/guardrail-margin-protection.md - load: true - - name: "Setup: Discount Rules" - path: ecommerce/setup-discount-rules.md - load: true --- # Flow: Upsell Boost Campaign -> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`: -> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-discount-conflicts) -> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-margin-protection) -> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-discount-rules) +> **Before executing this skill**, read [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) with `ReadFullDocsArticle` — it contains the discount-rule mechanics **and** the pre-create guardrails (conflict/stacking, margin floor, %-sanity). Creates a discount that incentivizes customers to spend more per order by setting a minimum subtotal threshold above the store's current AOV. The discount percentage is scaled to the store's average profit margin, and the scope targets high-margin categories or products. @@ -114,36 +100,7 @@ Max 3 categoryIds per discount rule. ## Step 6: Run guardrail checks -**IMPORTANT: Run both guardrail checks before creating the discount rule.** - -### 6a: Discount Conflicts - -1. Query existing active discount rules: - -**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query` - -**Request**: -```json -{ - "query": { - "filter": { - "active": true - }, - "paging": { - "limit": 100 - } - } -} -``` - -2. Check for scope overlap, time overlap, and coupon stacking risks with the planned upsell discount. -3. If conflicts found, present to merchant and get confirmation before proceeding. - -### 6b: Margin Protection - -Verify that `discount_percentage <= avg_profit_margin - 15%` (minMarginPct). If the discount would push effective margin below 15%, warn the merchant. - -The global discount cap is 25%. Do not exceed this unless the merchant explicitly overrides it. +**Run the pre-create guardrails in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails" before creating the rule** — conflict/stacking (scope, time, coupon cross-stacking), the 25% cap, the 15% margin floor, and %-sanity. Present any warnings to the merchant and get confirmation before proceeding. --- diff --git a/skills/wix-manage/references/ecommerce/goal-clear-inventory.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-goal-clear-inventory.md similarity index 87% rename from skills/wix-manage/references/ecommerce/goal-clear-inventory.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-goal-clear-inventory.md index 36bd45e3..b53b40ca 100644 --- a/skills/wix-manage/references/ecommerce/goal-clear-inventory.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-goal-clear-inventory.md @@ -1,22 +1,10 @@ --- name: "Goal: Clear Inventory" description: Maps the STOCK_MOVER business goal to inventory turnover KPIs and clearance discount flows. -layer: goal -references: - - name: "Flow: Stock Mover" - path: ecommerce/flow-stock-mover.md - load: true - - name: "Guardrail: Margin Protection" - path: ecommerce/guardrail-margin-protection.md - load: false --- # Goal: Clear Slow-Moving Inventory -> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`: -> - [Flow: Stock Mover](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-stock-mover) -> -> **Related skills** (read with `ReadFullDocsArticle` if needed): -> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-margin-protection) +> **Before executing this skill**, read [Flow: Stock Mover](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-stock-mover) with `ReadFullDocsArticle`. The margin-floor guardrail (critical for clearance) is enforced in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails". Automate clearance discounts for products with high stock levels and low sales velocity, converting stagnant inventory into revenue before it becomes a carrying cost liability. diff --git a/skills/wix-manage/references/ecommerce/goal-drive-cross-sells.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-goal-drive-cross-sells.md similarity index 97% rename from skills/wix-manage/references/ecommerce/goal-drive-cross-sells.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-goal-drive-cross-sells.md index 518b6d1c..a3e9dcef 100644 --- a/skills/wix-manage/references/ecommerce/goal-drive-cross-sells.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-goal-drive-cross-sells.md @@ -1,11 +1,6 @@ --- name: "Goal: Drive Cross-Sells" description: Maps the BUNDLE_AND_SAVE business goal to multi-item purchase KPIs and bundling flows. -layer: goal -references: - - name: "Flow: Bundle and Save" - path: ecommerce/flow-bundle-and-save.md - load: true --- # Goal: Drive Cross-Sells and Product Discovery diff --git a/skills/wix-manage/references/ecommerce/goal-increase-aov.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-goal-increase-aov.md similarity index 83% rename from skills/wix-manage/references/ecommerce/goal-increase-aov.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-goal-increase-aov.md index 0ee58615..112ca57f 100644 --- a/skills/wix-manage/references/ecommerce/goal-increase-aov.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-goal-increase-aov.md @@ -1,23 +1,6 @@ --- name: "Goal: Increase AOV" description: Maps the UPSELL_BOOST business goal to measurable KPIs and actionable discount flows. Covers AOV benchmarking, margin-based discount tiers, and minSubTotal strategy. -layer: goal -references: - - name: "Flow: Upsell Boost" - path: ecommerce/flow-upsell-boost.md - load: true - - name: "Flow: Bundle and Save" - path: ecommerce/flow-bundle-and-save.md - load: true - - name: "Flow: Add Free Shipping" - path: ecommerce/flow-add-free-shipping.md - load: false - - name: "Flow: Optimize Shipping Rates" - path: ecommerce/flow-optimize-shipping-rates.md - load: false - - name: "Guardrail: Margin Protection" - path: ecommerce/guardrail-margin-protection.md - load: false --- # Goal: Increase Average Order Value @@ -26,11 +9,10 @@ references: > - [Flow: Bundle and Save](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-bundle-and-save) > > **Shipping flows that also serve AOV goals** (load if shipping domain is active): -> - [Flow: Add Free Shipping](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-add-free-shipping) — free shipping threshold pushes carts above AOV -> - [Flow: Optimize Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-optimize-shipping-rates) — rate optimization improves conversion on higher-value orders +> - [Flow: Add Free Shipping](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-add-free-shipping) — free shipping threshold pushes carts above AOV +> - [Flow: Optimize Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-optimize-rates) — rate optimization improves conversion on higher-value orders > -> **Related skills** (read with `ReadFullDocsArticle` if needed): -> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-margin-protection) +> The margin/cap guardrails are enforced in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails". Incentivize customers to spend above the store's current average order value (AOV) by creating threshold-based discounts that reward higher cart totals. diff --git a/skills/wix-manage/references/ecommerce/goal-seasonal-revenue.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-goal-seasonal-revenue.md similarity index 97% rename from skills/wix-manage/references/ecommerce/goal-seasonal-revenue.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-goal-seasonal-revenue.md index d8a509f8..64ca03dc 100644 --- a/skills/wix-manage/references/ecommerce/goal-seasonal-revenue.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-goal-seasonal-revenue.md @@ -1,11 +1,6 @@ --- name: "Goal: Seasonal Revenue" description: Maps the SEASONAL business goal to event-driven revenue KPIs and promotional flows. -layer: goal -references: - - name: "Flow: Seasonal Promotion" - path: ecommerce/flow-seasonal-promotion.md - load: true --- # Goal: Capitalize on Seasonal Events diff --git a/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-health.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-health.md new file mode 100644 index 00000000..b610d185 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-health.md @@ -0,0 +1,28 @@ +--- +name: "Pricing & Discount Health" +description: Periodic review of a store's pricing and promotions — finds discount conflicts/stacking, stale sales with no end date, and margin-erosion risk across all active discounts and coupons. Triggers on "pricing health", "review my discounts", "discount conflicts check", "are my sales still running". +--- + +# Pricing & Discount Health + +A periodic audit of all active discounts and coupons — surfaces problems before they cost margin or confuse customers. Run proactively (digest) and report only findings. + +## Step 1: Gather active promotions + +- Discount rules: `POST https://www.wixapis.com/ecom/v1/discount-rules/query` with `filter: { "active": true }`. +- Coupons: `POST https://www.wixapis.com/stores/v2/coupons/query`. + +## Step 2: Checks (reuse the create-time guardrails, applied across the whole set) + +| Check | How | Flag | +|---|---|---| +| **Stacking conflicts** | scope/time overlap between active rules (and rule↔coupon cross-stacking) | overlapping scope on same products → combined discount deeper than intended | +| **Stale sales** | rules `active: true` with no `activeTimeInfo.end` (or an end far in the past/none) | "running indefinitely with no end date" | +| **Margin erosion** | any active discount > 25% cap, or combined stacked discount pushing effective margin < 15% | cap/floor breach | +| **Orphaned / ineffective** | rules that never apply (scope matches no products, or eligibility never met) | dead rule — recommend deactivating | + +These are the same rules enforced at creation in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails" — this skill applies them as a periodic sweep over everything already live. + +## Step 3: Report + +Severity-ranked: **stacking/margin breaches** (costing money now) first, then **stale sales**, then **cleanup** (orphaned rules). For each, name the rule(s) and the concrete fix (deactivate, add an end date, lower the discount). To fix a discount that *should* apply but isn't, see [Troubleshoot: Discount Not Applying](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-discount-not-applying). diff --git a/skills/wix-manage/references/ecommerce/recommend-ecommerce-strategy.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-run-a-sale.md similarity index 93% rename from skills/wix-manage/references/ecommerce/recommend-ecommerce-strategy.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-run-a-sale.md index cd81cd87..bf3a17ad 100644 --- a/skills/wix-manage/references/ecommerce/recommend-ecommerce-strategy.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-run-a-sale.md @@ -1,5 +1,5 @@ --- -name: "Recommend: eCommerce Strategy" +name: "Pricing: Run a Sale (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. layer: R references: @@ -19,13 +19,15 @@ references: path: ecommerce/goal-drive-cross-sells.md load: false - name: "Goal: Reduce Cart Abandonment" - path: ecommerce/goal-reduce-cart-abandonment.md + path: ecommerce/checkout/ecom-checkout-reduce-abandonment.md load: false - name: "Setup: Coupons" path: ecommerce/setup-coupons.md load: false --- -# Recommend: eCommerce Strategy +# Run a Sale (Recommend eCommerce Strategy) + +> **Routing note.** Reached via dispatch from [Pricing & Promotions](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-promotions) when the merchant tags as `run-a-sale | boost-business | seasonal-promo | clearance | increase-aov`. The dispatcher pre-loaded MerchantContext via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context) — **Step 1 (resolve siteId) and Step 3 (load business profile) below are safe to skip if `siteData.country` is already in your conversation context.** Step 2 (tracking history) is orchestrator-specific and **must still run**. > > **After classifying domains in Step 4b**, load the matching goal skill with `ReadFullDocsArticle`: @@ -33,10 +35,10 @@ references: > - **UPSELL_BOOST** / **SHIPPING** → [Goal: Increase AOV](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-increase-aov) (includes both discount and shipping flows) > - **STOCK_MOVER** → [Goal: Clear Inventory](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-clear-inventory) > - **BUNDLE_AND_SAVE** → [Goal: Drive Cross-Sells](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-drive-cross-sells) -> - **ABANDONED_CART** → [Goal: Reduce Cart Abandonment](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-reduce-cart-abandonment) +> - **ABANDONED_CART** → [Goal: Reduce Cart Abandonment](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/checkout-reduce-abandonment) *(will move under Checkout & cart category)* > > **If COUPON mechanism in Step 4c**, load: -> - [Setup: Coupons](https://dev.wix.com/docs/api-reference/business-solutions/coupons) +> - [Create Coupon](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-coupon) ## EXECUTION RULES — READ BEFORE ANYTHING ELSE @@ -48,6 +50,7 @@ references: 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. + - The `manage.wix.com/_api/agentic-recommendations/...` and `manage.wix.com/recommendations/v1/recommendations/...-tool` endpoints are **internal Wix services** — they have NO public `dev.wix.com` docs page, but they **ARE callable via `CallWixSiteAPI`** in the authenticated editor/dashboard context the MCP runs in. Do not treat them as unavailable and do not try to `ReadFullDocsArticle` them — the request/response specs inline in this recipe (and in [API: Recommendation Tracking](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-recommendation-tracking)) are the authoritative source. 7. **Generate recommendations across ALL relevant domains** — not just discounts. Consider shipping, discounts, and any other domain that the data supports. --- @@ -207,7 +210,7 @@ Based on the merchant's request AND the site data, determine which domains to an **For ABANDONED_CART domain — load the cart abandonment goal:** -[Goal: Reduce Cart Abandonment](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-reduce-cart-abandonment) +[Goal: Reduce Cart Abandonment](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/checkout-reduce-abandonment) **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. diff --git a/skills/wix-manage/references/ecommerce/api-recommendation-tracking.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-tracking-api.md similarity index 97% rename from skills/wix-manage/references/ecommerce/api-recommendation-tracking.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-tracking-api.md index 583f1b3e..54324172 100644 --- a/skills/wix-manage/references/ecommerce/api-recommendation-tracking.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-tracking-api.md @@ -1,7 +1,6 @@ --- name: "API: Recommendation Tracking" description: CRUD API for persisting and managing the lifecycle of AI-generated recommendations. Tracks state transitions from PROPOSED through APPROVED, EXECUTING, to DONE/FAILED/REJECTED. Every recommendation must be persisted here before presenting to the merchant. -layer: config --- # API: Recommendation Tracking Service @@ -11,6 +10,8 @@ This service persists recommendations in a database and tracks their lifecycle s **Base URL**: `https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations` +> **Internal-but-callable API.** This is a Wix-internal service with NO public `dev.wix.com` docs page. It **IS callable via `CallWixSiteAPI`** in the authenticated editor/dashboard context the MCP runs in (verified: the endpoints return auth/validation errors, not 404). This file is the authoritative spec — do not try to `ReadFullDocsArticle` an external doc for it. + ## How to call these APIs Use `CallWixSiteAPI` to invoke each endpoint: diff --git a/skills/wix-manage/references/ecommerce/troubleshoot-discount-not-applying.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-troubleshoot-not-applying.md similarity index 98% rename from skills/wix-manage/references/ecommerce/troubleshoot-discount-not-applying.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-troubleshoot-not-applying.md index 555ef0bb..e885256d 100644 --- a/skills/wix-manage/references/ecommerce/troubleshoot-discount-not-applying.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-troubleshoot-not-applying.md @@ -1,5 +1,5 @@ --- -name: "Troubleshoot: Discount Not Applying" +name: "Pricing: Discount Not Applying" description: Diagnostic tree for when a discount rule exists but isn't applying at checkout. Checks active status, time window, scope targeting, revision, and app installation. layer: troubleshoot --- diff --git a/skills/wix-manage/references/ecommerce/recipe-apply-shipping-recommendations.md b/skills/wix-manage/references/ecommerce/recipe-apply-shipping-recommendations.md deleted file mode 100644 index 1cac4e2f..00000000 --- a/skills/wix-manage/references/ecommerce/recipe-apply-shipping-recommendations.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -name: "Recipe: Apply Shipping Recommendations" -description: Applies AI-generated shipping recommendations to a Wix e-commerce store. Reads the current delivery profile and shipping options, then creates or updates shipping options based on recommendation data. Supports creating new options with conditional rates, updating existing options, and querying delivery profiles for region/carrier context. ---- -# Apply Shipping Recommendations - -## Prerequisites - -- Wix Stores (or another eCommerce business solution) installed on the site -- Shipping recommendations data available (from the AI recommendation system or provided directly) - -## Required APIs - -- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles) -- [Get Delivery Profile](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#get-delivery-profile) - ---- - -## Step 1: Query the current shipping configuration - -Call [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles) to understand the site's delivery setup — profiles, regions, carriers, and backup rates. - -**Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/query` - -**Request**: -```json -{ - "query": { - "cursorPaging": { - "limit": 100 - } - } -} -``` - -**Response**: -```json -{ - "deliveryProfiles": [ - { - "id": "6a9b2f9b-533a-4d0d-ac8d-64ec3f32fcbd", - "name": "General profile", - "default": true, - "deliveryRegions": [ - { - "id": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c", - "name": "Domestic", - "active": true, - "deliveryCarriers": [ - { - "appId": "45c44b27-ca7b-4891-8c0d-1747d588b835", - "additionalCharges": [] - } - ], - "destinations": [ - { - "countryCode": "GB", - "subdivisions": [] - } - ] - } - ], - "revision": "43", - "createdDate": "2025-10-26T11:05:10.774Z", - "updatedDate": "2026-04-14T14:43:25.397Z" - } - ], - "pagingMetadata": { - "count": 1, - "cursors": {}, - "hasNext": false - } -} -``` - -Save the profile `id`, `revision`, and each region's `id` and `active` status. Identify which regions have carriers with missing backup rates (`backupRate` absent or `backupRate.active: false`). - ---- - -## Step 2: Query existing shipping options - -**Endpoint**: `POST https://www.wixapis.com/ecom/v1/shipping-options/query` - -**Request**: -```json -{ - "query": { - "cursorPaging": { - "limit": 100 - } - } -} -``` - -**Response**: -```json -{ - "shippingOptions": [ - { - "id": "c0e5be8f-5266-4720-a732-5f571e4750db", - "revision": "1", - "createdDate": "2026-04-14T14:43:24.804Z", - "updatedDate": "2026-04-14T14:43:24.804Z", - "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c", - "deliveryRegionIds": [], - "title": "Standard Shipping", - "estimatedDeliveryTime": "5-7 business days", - "rates": [ - { - "amount": "15.00", - "conditions": [], - "multiplyByQuantity": false - } - ] - } - ], - "pagingMetadata": { - "count": 1, - "cursors": {}, - "hasNext": false - } -} -``` - -Note: The response uses `deliveryRegionId` (singular) as the primary field linking an option to a region. - ---- - -## Step 3: Apply recommendation — Create a new shipping option - -When the recommendation action is `create_shipping_option`, create a new option linked to a specific delivery region. - -**Endpoint**: `POST https://www.wixapis.com/ecom/v1/shipping-options` - -**Request** — flat rate example: -```json -{ - "shippingOption": { - "title": "Express Shipping", - "estimatedDeliveryTime": "1-2 business days", - "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c", - "rates": [ - { - "amount": "12.99", - "multiplyByQuantity": false, - "conditions": [] - } - ] - } -} -``` - -**Response**: -```json -{ - "shippingOption": { - "id": "dece6160-4e72-4fcc-adcc-7607215edab0", - "revision": "1", - "createdDate": "2026-04-15T13:14:01.214Z", - "updatedDate": "2026-04-15T13:14:01.214Z", - "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c", - "deliveryRegionIds": [], - "title": "Express Shipping", - "estimatedDeliveryTime": "1-2 business days", - "rates": [ - { - "amount": "12.99", - "conditions": [], - "multiplyByQuantity": false - } - ] - } -} -``` - -**Request** — free shipping with price threshold: -```json -{ - "shippingOption": { - "title": "Free Shipping", - "estimatedDeliveryTime": "5-7 business days", - "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c", - "rates": [ - { - "amount": "0", - "multiplyByQuantity": false, - "conditions": [ - { - "type": "BY_TOTAL_PRICE", - "operator": "GTE", - "value": "75" - } - ] - } - ] - } -} -``` - -**Key field rules:** - -| Field | Required | Notes | -|---|---|---| -| `title` | Yes | Display name at checkout | -| `estimatedDeliveryTime` | Yes | Free text shown to customers | -| `deliveryRegionId` | Yes | Region UUID from Step 1. Must use **singular** field, not `deliveryRegionIds` | -| `rates` | Yes | Array of rate objects | -| `rates[].amount` | Yes | Decimal string (`"5.99"`, `"0"` for free) | -| `rates[].multiplyByQuantity` | Yes | Almost always `false` | -| `rates[].conditions` | Yes | Empty array for flat rate; see condition types below | - -**Condition types** (for tiered/conditional rates): - -| Type | Description | Example | -|---|---|---| -| `BY_TOTAL_PRICE` | Cart total threshold | `"operator": "GTE", "value": "75"` | -| `BY_TOTAL_WEIGHT` | Weight threshold | `"operator": "LTE", "value": "10"` | -| `BY_TOTAL_QUANTITY` | Item count threshold | `"operator": "GTE", "value": "3"` | - -Operators: `EQ`, `GT`, `GTE`, `LT`, `LTE` - ---- - -## Step 4: Apply recommendation — Update an existing shipping option - -When the recommendation action is `update_shipping_option`, update an existing option's title, delivery time, or rates. - -**Endpoint**: `PATCH https://www.wixapis.com/ecom/v1/shipping-options/{shippingOptionId}` - -Replace `{shippingOptionId}` with the option's `id` from Step 2. - -**Request**: -```json -{ - "shippingOption": { - "id": "c0e5be8f-5266-4720-a732-5f571e4750db", - "revision": "1", - "title": "Updated Standard Shipping", - "estimatedDeliveryTime": "3-5 business days", - "rates": [ - { - "amount": "9.99", - "multiplyByQuantity": false, - "conditions": [] - } - ] - } -} -``` - -**Response**: -```json -{ - "shippingOption": { - "id": "c0e5be8f-5266-4720-a732-5f571e4750db", - "revision": "2", - "createdDate": "2026-04-14T14:43:24.804Z", - "updatedDate": "2026-04-15T13:14:13.716Z", - "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c", - "deliveryRegionIds": [], - "title": "Updated Standard Shipping", - "estimatedDeliveryTime": "3-5 business days", - "rates": [ - { - "amount": "9.99", - "conditions": [], - "multiplyByQuantity": false - } - ] - } -} -``` - -The `revision` field is required and must match the current revision. The response returns the incremented revision. - ---- - -## Step 5: Verify the changes - -After applying recommendations, query shipping options again (Step 2) to confirm the changes took effect. Verify: - -- New options appear in the list with the correct title, rates, and region link -- Updated options reflect the new values and incremented revision -- The option is linked to the correct `deliveryRegionId` - ---- - -## Error Handling - -| Error | Cause | Fix | -|---|---|---| -| `deliveryRegionId is not a valid GUID` | Used `deliveryRegionIds` (plural) instead of `deliveryRegionId` (singular) in create request | Use the singular `deliveryRegionId` field | -| `SHIPPING_OPTION_NOT_FOUND` | The shipping option ID doesn't exist | Re-query shipping options to get current IDs | -| `REVISION_MISMATCH` | The `revision` doesn't match the current version | Re-fetch the option to get the latest revision, then retry | - -## References - -- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping) \ No newline at end of file diff --git a/skills/wix-manage/references/ecommerce/api-shipping.md b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-api.md similarity index 97% rename from skills/wix-manage/references/ecommerce/api-shipping.md rename to skills/wix-manage/references/ecommerce/shipping/ecom-shipping-api.md index f98ffe3b..9226aef6 100644 --- a/skills/wix-manage/references/ecommerce/api-shipping.md +++ b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-api.md @@ -1,7 +1,6 @@ --- -name: "API: Shipping Delivery" +name: "Shipping: API Reference" description: REST API reference for Shipping Options and Delivery Profiles. Covers CRUD operations, region/carrier management, and query patterns for both services. Internal reference — these APIs are not yet published in public docs. -layer: config --- # API: Shipping Delivery @@ -73,6 +72,8 @@ Creates a new shipping option and associates it with one or more delivery region **Required fields**: `shippingOption.deliveryRegionId` (or `deliveryRegionIds`), `shippingOption.title`, `shippingOption.rates[]` +> **Gotcha:** use the **singular** `deliveryRegionId` when linking an option to one region. Passing a single region in the plural `deliveryRegionIds` field returns `deliveryRegionId is not a valid GUID`. + **Request**: ```json { diff --git a/skills/wix-manage/references/ecommerce/flow-fix-coverage-gaps.md b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-fix-coverage.md similarity index 83% rename from skills/wix-manage/references/ecommerce/flow-fix-coverage-gaps.md rename to skills/wix-manage/references/ecommerce/shipping/ecom-shipping-fix-coverage.md index edb1c16a..6260af73 100644 --- a/skills/wix-manage/references/ecommerce/flow-fix-coverage-gaps.md +++ b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-fix-coverage.md @@ -1,20 +1,26 @@ --- -name: "Flow: Fix Coverage Gaps" +name: "Shipping: Fix Coverage Gaps" description: Detects active delivery regions with zero shipping options and creates standard shipping for them. Cross-references delivery profiles with shipping options to find regions where customers cannot complete checkout. -layer: flow -references: - - name: "Guardrail: Shipping Health" - path: ecommerce/guardrail-shipping-health.md - load: true - - name: "Setup: Shipping Regions" - path: ecommerce/setup-shipping-regions.md - load: true --- # Flow: Fix Shipping Coverage Gaps -> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`: -> - [Guardrail: Shipping Health](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-shipping-health) -> - [Setup: Shipping Regions](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-shipping-regions) +> **Before executing this skill**, read [Setup: Shipping Regions](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-regions) with `ReadFullDocsArticle` for region/carrier mechanics. + +## Shipping health score (inline) + +Use to gauge urgency before fixing gaps: + +| Score | Key indicator | Action | +|---|---|---| +| CRITICAL | no profiles/options, or all regions inactive | immediate setup | +| POOR | minimal config, low CVR, or no backup rates | fix fundamentals | +| FAIR | basic setup, no free shipping, moderate CVR | add free shipping, expand regions | +| GOOD | domestic + international, free shipping, good CVR | optimize rates/carriers | +| EXCELLENT | full coverage, tiered rates, high CVR | maintain | + +## Business-context filter for international (MANDATORY) + +Before creating or recommending ANY international shipping, check the store's `industry`/`businessType` (case-insensitive) for: food, restaurant, grocery, bakery, catering, perishable, fresh, meat, produce, dairy, drink, beverage. **If matched → do NOT create/recommend international shipping** (cold-chain & regulatory barriers). A region is "international" if its `name` contains "international"/"internacional", its `destinations[]` is empty (Rest of World), or it includes countries outside the store's home country. Detects delivery regions where customers cannot see any shipping options at checkout and creates standard shipping to fill the gaps. A coverage gap is a HIGH priority blocking issue -- customers in affected destinations literally cannot complete a purchase. @@ -26,9 +32,9 @@ Detects delivery regions where customers cannot see any shipping options at chec ## Required APIs -- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles) -- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-shipping-options) -- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#create-shipping-option) +- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-delivery-profiles) +- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-shipping-options) +- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#create-shipping-option) --- @@ -296,4 +302,4 @@ Use the same request from Step 2 and verify the count now covers all active, non ## References -- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping) +- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference) diff --git a/skills/wix-manage/references/ecommerce/flow-add-free-shipping.md b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-free-shipping.md similarity index 86% rename from skills/wix-manage/references/ecommerce/flow-add-free-shipping.md rename to skills/wix-manage/references/ecommerce/shipping/ecom-shipping-free-shipping.md index ce40a573..864c9547 100644 --- a/skills/wix-manage/references/ecommerce/flow-add-free-shipping.md +++ b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-free-shipping.md @@ -1,20 +1,23 @@ --- -name: "Flow: Add Free Shipping" +name: "Shipping: Add Free Shipping" description: Creates a free shipping option with an AOV-calibrated threshold to reduce cart abandonment and increase average order value. Validates threshold against catalog price distribution. -layer: flow -references: - - name: "Guardrail: Rate Pricing Sanity" - path: ecommerce/guardrail-rate-pricing-sanity.md - load: true - - name: "Setup: Shipping Rates" - path: ecommerce/setup-shipping-rates.md - load: true --- # Flow: Add Free Shipping -> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`: -> - [Guardrail: Rate Pricing Sanity](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-rate-pricing-sanity) -> - [Setup: Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-shipping-rates) +> **Before executing this skill**, read [Setup: Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-rates) with `ReadFullDocsArticle` for the rate-object mechanics. + +## Rate pricing sanity (inline guardrail) + +Validate every rate you create or update against the store's AOV; flag any that fail: + +| Check | Threshold | Why / fix | +|---|---|---| +| Excessive rate | amount > AOV × 0.15 | top cart-abandonment driver | +| Per-item penalty | `multiplyByQuantity: true` | penalizes larger orders → use flat/tiered | +| Free threshold too high | threshold > AOV × 2 | unreachable; lower to ~AOV × 1.2 | +| Free threshold too low | threshold < AOV × 0.8 | no upsell incentive; raise to ~AOV × 1.2 | +| Backup rate shock | `backupRate.amount` > AOV × 0.15 | set to 5–10% of AOV | +| Hidden surcharges | total `additionalCharges` > AOV × 0.10 | review necessity | Adds a free shipping option with an optimal threshold calibrated against the site's average order value and catalog price distribution. Free shipping is the single most effective lever for reducing cart abandonment at the delivery step. @@ -27,10 +30,10 @@ Adds a free shipping option with an optimal threshold calibrated against the sit ## Required APIs -- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-shipping-options) -- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#create-shipping-option) -- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#update-shipping-option) -- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles) +- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-shipping-options) +- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#create-shipping-option) +- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#update-shipping-option) +- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-delivery-profiles) --- @@ -263,4 +266,4 @@ Report to the merchant: ## References -- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping) +- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference) diff --git a/skills/wix-manage/references/ecommerce/flow-optimize-shipping-rates.md b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-optimize-rates.md similarity index 88% rename from skills/wix-manage/references/ecommerce/flow-optimize-shipping-rates.md rename to skills/wix-manage/references/ecommerce/shipping/ecom-shipping-optimize-rates.md index 06ec0a0d..07182058 100644 --- a/skills/wix-manage/references/ecommerce/flow-optimize-shipping-rates.md +++ b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-optimize-rates.md @@ -1,20 +1,23 @@ --- -name: "Flow: Optimize Shipping Rates" +name: "Shipping: Optimize Rates" description: Analyzes catalog price distribution and current rate structure to recommend optimal shipping rate strategy. Handles flat-to-tiered conversion, tier gap detection, and per-item penalty removal. -layer: flow -references: - - name: "Guardrail: Rate Pricing Sanity" - path: ecommerce/guardrail-rate-pricing-sanity.md - load: true - - name: "Setup: Shipping Rates" - path: ecommerce/setup-shipping-rates.md - load: true --- # Flow: Optimize Shipping Rates -> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`: -> - [Guardrail: Rate Pricing Sanity](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-rate-pricing-sanity) -> - [Setup: Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-shipping-rates) +> **Before executing this skill**, read [Setup: Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-rates) with `ReadFullDocsArticle` for the rate-object mechanics. + +## Rate pricing sanity (inline guardrail) + +Validate every rate you create or update against the store's AOV; flag any that fail: + +| Check | Threshold | Why / fix | +|---|---|---| +| Excessive rate | amount > AOV × 0.15 | top cart-abandonment driver | +| Per-item penalty | `multiplyByQuantity: true` | penalizes larger orders → use flat/tiered | +| Free threshold too high | threshold > AOV × 2 | unreachable; lower to ~AOV × 1.2 | +| Free threshold too low | threshold < AOV × 0.8 | no upsell incentive; raise to ~AOV × 1.2 | +| Backup rate shock | `backupRate.amount` > AOV × 0.15 | set to 5–10% of AOV | +| Hidden surcharges | total `additionalCharges` > AOV × 0.10 | review necessity | Analyzes the site's catalog price distribution and current shipping rate structure to determine if the rate strategy is optimal. Recommends and applies changes when flat rates should become tiered, when tier gaps exist, or when per-item penalties are harming conversion. @@ -27,9 +30,9 @@ Analyzes the site's catalog price distribution and current shipping rate structu ## Required APIs -- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-shipping-options) -- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#update-shipping-option) -- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#create-shipping-option) +- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-shipping-options) +- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#update-shipping-option) +- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#create-shipping-option) --- @@ -360,4 +363,4 @@ Verify: ## References -- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping) +- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference) diff --git a/skills/wix-manage/references/ecommerce/setup-store-pickup-location.md b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-setup-pickup.md similarity index 85% rename from skills/wix-manage/references/ecommerce/setup-store-pickup-location.md rename to skills/wix-manage/references/ecommerce/shipping/ecom-shipping-setup-pickup.md index dcafdb8c..f4c3d621 100644 --- a/skills/wix-manage/references/ecommerce/setup-store-pickup-location.md +++ b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-setup-pickup.md @@ -1,5 +1,5 @@ --- -name: "Setup: Store Pickup Location" +name: "Shipping: Set Up Pickup / Local Delivery" description: Configures a pickup option for an online store so customers can choose in-store pickup at checkout. Uses the Delivery Profiles API to discover the Pickup carrier, add a delivery region, and attach the carrier with a free pickup rate. --- # Set Up Store Pickup Location @@ -11,16 +11,16 @@ description: Configures a pickup option for an online store so customers can cho ## Required APIs -- [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#list-installed-delivery-carriers) -- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles) -- [Add Delivery Region](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#add-delivery-region) -- [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#add-delivery-carrier) +- [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#list-installed-delivery-carriers) +- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-delivery-profiles) +- [Add Delivery Region](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#add-delivery-region) +- [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#add-delivery-carrier) --- ## Step 1: Discover the Pickup carrier -Call [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#list-installed-delivery-carriers) to find the Pickup carrier's `id`. +Call [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#list-installed-delivery-carriers) to find the Pickup carrier's `id`. **Endpoint**: `GET https://www.wixapis.com/ecom/v1/delivery-profiles/installed-carriers` @@ -53,7 +53,7 @@ If no Pickup carrier appears in the list, the Pickup app is not installed on the ## Step 2: Find the default delivery profile -Call [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles) to retrieve the site's default delivery profile. +Call [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-delivery-profiles) to retrieve the site's default delivery profile. **Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/query` @@ -72,7 +72,7 @@ The response contains an array of `deliveryProfiles`. Find the one where `"defau ## Step 3: Add a delivery region for the pickup country -If no region exists for the user's country in the default profile, call [Add Delivery Region](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#add-delivery-region) to create one. +If no region exists for the user's country in the default profile, call [Add Delivery Region](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#add-delivery-region) to create one. **Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}/delivery-region` @@ -130,7 +130,7 @@ Save the new region's `id` from the response. ## Step 4: Add the Pickup carrier to the region -Call [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#add-delivery-carrier) to attach the Pickup carrier to the delivery region. +Call [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#add-delivery-carrier) to attach the Pickup carrier to the delivery region. **Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/add-delivery-carrier` @@ -205,4 +205,4 @@ Call [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solu ## Related Documentation -- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping) +- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference) diff --git a/skills/wix-manage/references/ecommerce/setup-shipping-rates.md b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-setup-rates.md similarity index 98% rename from skills/wix-manage/references/ecommerce/setup-shipping-rates.md rename to skills/wix-manage/references/ecommerce/shipping/ecom-shipping-setup-rates.md index 3260bfad..a3f153ef 100644 --- a/skills/wix-manage/references/ecommerce/setup-shipping-rates.md +++ b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-setup-rates.md @@ -1,7 +1,6 @@ --- -name: "Setup: Shipping Rates" +name: "Shipping: Set Up Rates" description: Configures shipping option rates — rate types (flat, tiered, free), condition types and operators, free shipping threshold calibration, AOV sanity check, per-item penalty avoidance, and tier gap detection. -layer: config --- # Shipping Rates diff --git a/skills/wix-manage/references/ecommerce/setup-shipping-regions.md b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-setup-regions.md similarity index 97% rename from skills/wix-manage/references/ecommerce/setup-shipping-regions.md rename to skills/wix-manage/references/ecommerce/shipping/ecom-shipping-setup-regions.md index 2ac2c4e6..7b3270dc 100644 --- a/skills/wix-manage/references/ecommerce/setup-shipping-regions.md +++ b/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-setup-regions.md @@ -1,7 +1,6 @@ --- -name: "Setup: Shipping Regions" +name: "Shipping: Set Up Regions" description: Configures delivery profiles and regions — creating profiles, adding regions with destinations, assigning carriers, enabling backup rates, and handling externally managed regions. -layer: config --- # Shipping Regions diff --git a/skills/wix-manage/references/ecommerce/skill-graph.md b/skills/wix-manage/references/ecommerce/skill-graph.md index a19bf98e..7e0a3309 100644 --- a/skills/wix-manage/references/ecommerce/skill-graph.md +++ b/skills/wix-manage/references/ecommerce/skill-graph.md @@ -1,139 +1,170 @@ --- -name: "eCommerce Skill Graph" -description: Mermaid diagram showing how eCommerce skills connect — unified strategy entry point, goal/flow/guardrail chain, tracking inlined, troubleshoot as direct entries. +name: "Skill Graph" +description: Mermaid diagram of the eCommerce routing tree - WixREADME to category entry, promotion, and support files. Migrated categories: Tax, Pricing, Shipping, Checkout, Abandoned Carts, Fulfillment, and Orders. --- ## Skill Graph Diagram ```mermaid flowchart TB - MR["Merchant Request"] --> R - - subgraph R["R — Unified Entry Point"] - recommend-ecommerce-strategy + MR["Merchant Query"] --> README["WixREADME
(portal index - category-docs surface here)"] + + README --> TAX + README --> PRICE + README --> SHIP + README --> CHECKOUT + README --> ABANDONED + README --> FULFILL + README --> ORDERS + + LOADER["ecom-load-context.md
(L1 loader - general site data;
loaded by each category before dispatch)"] + TAX -.-> |load context| LOADER + PRICE -.-> |load context| LOADER + SHIP -.-> |load context| LOADER + CHECKOUT -.-> |load context| LOADER + ABANDONED -.-> |load context| LOADER + FULFILL -.-> |load context| LOADER + ORDERS -.-> |load context| LOADER + + subgraph TAX["Tax - tax/"] + direction TB + TAXDEF["ecom-tax - category-doc + dispatcher"] + TC["ecom-tax-configure"] + TA["ecom-tax-avalara"] + TV["ecom-tax-eu-vat"] + TS["ecom-tax-switch-calculator"] + TU["ecom-tax-audit"] + TT["ecom-tax-troubleshoot-calc-wrong"] + TAXDEF ~~~ TC ~~~ TA ~~~ TV ~~~ TS ~~~ TU ~~~ TT end - R --> |"loads API ref"| Config - R --> |"Step 4b: loads matching goal"| Goals - R --> |"Step 2+8: tracking inlined"| TrackingAPI - - subgraph Goals["Goals — Business Objectives"] - subgraph GD["Discount + Shipping"] - goal-increase-aov - goal-clear-inventory - goal-seasonal-revenue - goal-drive-cross-sells - end - subgraph GA["Abandoned Cart"] - goal-reduce-cart-abandonment - end + subgraph PRICE["Pricing & promotions - pricing-promotions/"] + direction TB + PRICEDEF["ecom-pricing - category-doc + dispatcher"] + PC["ecom-pricing-create-coupon"] + PD["ecom-pricing-create-discount-rule"] + PR["ecom-pricing-run-a-sale - business-flow orchestrator"] + PB["ecom-pricing-troubleshoot-not-applying"] + PH["ecom-pricing-health"] + PG["goal-* support files"] + PF["flow-* support files"] + PV["tracking-api"] + PRICEDEF ~~~ PC ~~~ PD ~~~ PR ~~~ PB ~~~ PH ~~~ PG ~~~ PF ~~~ PV end - Goals --> |"loads matching flows"| Flows - goal-increase-aov --> |"also loads shipping flows"| FS - - subgraph Flows["Flows — Business Logic"] - subgraph FD["Discount"] - flow-upsell-boost - flow-bundle-and-save - flow-stock-mover - flow-seasonal-promotion - end - subgraph FS["Shipping"] - flow-fix-coverage-gaps - flow-add-free-shipping - flow-optimize-shipping-rates - end + subgraph SHIP["Shipping - shipping/"] + direction TB + SHIPDEF["ecom-shipping - category-doc + dispatcher"] + SR["ecom-shipping-setup-rates"] + SG["ecom-shipping-setup-regions"] + SP["ecom-shipping-setup-pickup"] + SF["ecom-shipping-free-shipping"] + SO["ecom-shipping-optimize-rates"] + SX["ecom-shipping-fix-coverage"] + SS["ecom-shipping-api"] + SHIPDEF ~~~ SR ~~~ SG ~~~ SP ~~~ SF ~~~ SO ~~~ SX ~~~ SS end - Flows --> |"loads validation"| Guardrails - Flows --> |"loads setup"| Config - - subgraph Guardrails["Cross-cutting: Guardrails"] - guardrail-discount-conflicts - guardrail-margin-protection - guardrail-shipping-health - guardrail-rate-pricing-sanity + subgraph CHECKOUT["Checkout & cart - checkout/"] + direction TB + CHKDEF["ecom-checkout - category-doc + dispatcher"] + CR["ecom-checkout-reduce-abandonment"] + CT["ecom-checkout-troubleshoot-dropoff"] + CA["ecom-checkout-agentic-readiness"] + CH["ecom-checkout-store-health"] + CD["config intents -> Wix Dashboard"] + CHKDEF ~~~ CR ~~~ CT ~~~ CA ~~~ CH ~~~ CD end - subgraph Config["Config — Setup & API References"] - setup-discount-rules - setup-coupons - setup-shipping-regions - setup-shipping-rates - api-shipping + subgraph ABANDONED["Abandoned carts - abandoned-carts/"] + direction TB + ACDEF["ecom-abandoned-carts - category-doc + dispatcher"] + AR["ecom-abandoned-carts-recover-email"] + AL["ecom-abandoned-carts-recovery-link"] + AT["ecom-abandoned-carts-troubleshoot-recovery"] + AH["ecom-abandoned-carts-recovery-health"] + ACDEF ~~~ AR ~~~ AL ~~~ AT ~~~ AH end - subgraph TrackingAPI["Tracking API"] - api-recommendation-tracking + subgraph FULFILL["Fulfillment - fulfillment/"] + direction TB + FDEF["ecom-fulfillment - category-doc + dispatcher"] + FO["ecom-fulfillment-fulfill-orders"] + FB["ecom-fulfillment-bulk-fulfill-orders"] + FL["labels -> Wix Dashboard"] + FI["invoice / packing slip -> API route"] + FDEF ~~~ FO ~~~ FB ~~~ FL ~~~ FI end - subgraph Standalone["Direct Entry Points (from README)"] - recipe-apply-shipping-recommendations - setup-store-pickup-location - troubleshoot-discount-not-applying - troubleshoot-checkout-delivery-dropoff + subgraph ORDERS["Orders - orders/"] + direction TB + ODEF["ecom-orders - category-doc + dispatcher"] + OC["ecom-orders-cancel-order"] + OS["search / get / counts / pending -> Orders API (main-file routes)"] + OH["approve · return · manual-order · contact · notifications -> Dashboard / unverified"] + ODEF ~~~ OC ~~~ OS ~~~ OH end - Config -.-> |"calls via CallWixSiteAPI"| API - - subgraph API["Wix REST API Docs (dev.wix.com)"] - D1["Discount Rules API"] - D2["Coupons API"] - D3["Products V3 API"] - D4["Categories API"] - D5["Catalog Analytics"] - S3["Pickup Locations API"] - S4["Local Delivery API"] - SD["Profile Service API (wix-profile-client)"] - end - - classDef goal fill:#8b5cf6,stroke:#6d28d9,color:#fff - classDef guardrail fill:#ef4444,stroke:#dc2626,color:#fff - classDef flow fill:#3b82f6,stroke:#2563eb,color:#fff - classDef config fill:#f59e0b,stroke:#d97706,color:#fff - classDef reco fill:#ec4899,stroke:#db2777,color:#fff - classDef standalone fill:#6b7280,stroke:#4b5563,color:#fff - classDef apidoc fill:#e5e7eb,stroke:#9ca3af,color:#374151 - - class goal-increase-aov,goal-clear-inventory,goal-seasonal-revenue,goal-drive-cross-sells,goal-reduce-cart-abandonment goal - class guardrail-discount-conflicts,guardrail-margin-protection,guardrail-shipping-health,guardrail-rate-pricing-sanity guardrail - class flow-upsell-boost,flow-bundle-and-save,flow-stock-mover,flow-seasonal-promotion,flow-fix-coverage-gaps,flow-add-free-shipping,flow-optimize-shipping-rates flow - class setup-discount-rules,setup-coupons,setup-shipping-regions,setup-shipping-rates,api-recommendation-tracking,api-shipping config - class recommend-ecommerce-strategy reco - class recipe-apply-shipping-recommendations,setup-store-pickup-location,troubleshoot-discount-not-applying,troubleshoot-checkout-delivery-dropoff standalone - class D1,D2,D3,D4,D5,S1,S2,S3,S4,SD apidoc + classDef dispatcher fill:#f59e0b,stroke:#d97706,color:#fff + classDef promotion fill:#3b82f6,stroke:#2563eb,color:#fff + classDef orchestrator fill:#ec4899,stroke:#db2777,color:#fff + classDef support fill:#8b5cf6,stroke:#6d28d9,color:#fff + classDef loader fill:#10b981,stroke:#059669,color:#fff + classDef legacy fill:#6b7280,stroke:#4b5563,color:#fff + + class TAXDEF,PRICEDEF,SHIPDEF,CHKDEF,ACDEF,FDEF,ODEF dispatcher + class TC,TA,TV,TS,TU,TT,PC,PD,PB,PH,SR,SG,SP,SF,SO,SX,CR,CT,CA,CH,AR,AL,AT,AH,FO,FB,OC promotion + class PR orchestrator + class PG,PF,PV,SS,FI support + class LOADER loader + class CD,FL,OS,OH legacy ``` +The arrows land on each L2 group. Internal dispatch and support chains are documented in the reachability table below. + ## File Reachability -| File | Reached via | -|---|---| -| `recommend-ecommerce-strategy.md` | README routing (entry point) | -| `api-recommendation-tracking.md` | Entry point tracking steps | -| `goal-increase-aov.md` | Step 4b (UPSELL_BOOST) | -| `goal-clear-inventory.md` | Step 4b (STOCK_MOVER) | -| `goal-seasonal-revenue.md` | Step 4b (SEASONAL) | -| `goal-drive-cross-sells.md` | Step 4b (BUNDLE_AND_SAVE) | -| `goal-reduce-cart-abandonment.md` | Step 4b (ABANDONED_CART domain) | -| `flow-upsell-boost.md` | goal-increase-aov chain | -| `flow-bundle-and-save.md` | goal-increase-aov / goal-drive-cross-sells chain | -| `flow-stock-mover.md` | goal-clear-inventory chain | -| `flow-seasonal-promotion.md` | goal-seasonal-revenue chain | -| `flow-fix-coverage-gaps.md` | goal-reduce-cart-abandonment chain (critical operational fix) | -| `flow-add-free-shipping.md` | goal-increase-aov chain (shipping flows serving AOV) | -| `flow-optimize-shipping-rates.md` | goal-increase-aov chain (shipping flows serving AOV) | -| `guardrail-discount-conflicts.md` | flow-upsell-boost / bundle / stock / seasonal chains | -| `guardrail-margin-protection.md` | flow-upsell-boost / stock-mover chains | -| `guardrail-shipping-health.md` | flow-fix-coverage-gaps chain | -| `guardrail-rate-pricing-sanity.md` | flow-add-free-shipping / optimize chains | -| `setup-discount-rules.md` | All discount flow chains | -| `setup-coupons.md` | Step 4c (COUPON mechanism) | -| `setup-shipping-regions.md` | flow-fix-coverage-gaps chain | -| `setup-shipping-rates.md` | flow-add-free-shipping / optimize chains | -| `api-shipping.md` | Shipping flows (fix-coverage-gaps, add-free-shipping, optimize, recipe, setup-store-pickup) | -| `recipe-apply-shipping-recommendations.md` | README direct entry | -| `setup-store-pickup-location.md` | README direct entry | -| `troubleshoot-discount-not-applying.md` | README direct entry | -| `troubleshoot-checkout-delivery-dropoff.md` | README direct entry | -| `skill-graph.md` | Documentation reference | +| File | Role | Reached via | +|---|---|---| +| `ecom-load-context.md` | L1 loader | Loaded by eCommerce category dispatchers when MerchantContext is missing | +| `ecom-tax.md` | category-doc + dispatcher | WixREADME portal index | +| `tax/ecom-tax-configure.md` | promotion | tax dispatch `[intent:configure-tax]` | +| `tax/ecom-tax-avalara.md` | promotion | tax dispatch `[intent:avalara]` | +| `tax/ecom-tax-eu-vat.md` | promotion | tax dispatch `[intent:eu-vat]` | +| `tax/ecom-tax-switch-calculator.md` | promotion | tax dispatch `[intent:switch-calculator]` | +| `tax/ecom-tax-audit.md` | promotion | tax dispatch `[intent:audit-tax]` | +| `tax/ecom-tax-troubleshoot-calc-wrong.md` | promotion | tax dispatch `[intent:troubleshoot]` | +| `ecom-pricing.md` | category-doc + dispatcher | WixREADME portal index | +| `pricing-promotions/ecom-pricing-create-coupon.md` | promotion | pricing dispatch `[intent:create-coupon]` | +| `pricing-promotions/ecom-pricing-create-discount-rule.md` | promotion | pricing dispatch `[intent:create-discount-rule / add-ribbon / schedule-sale]` | +| `pricing-promotions/ecom-pricing-run-a-sale.md` | business-flow | pricing dispatch `[intent:run-a-sale / boost-business / seasonal-promo / clearance / increase-aov]` | +| `pricing-promotions/ecom-pricing-troubleshoot-not-applying.md` | promotion | pricing dispatch `[intent:troubleshoot]` | +| `pricing-promotions/ecom-pricing-health.md` | promotion | pricing dispatch `[intent:pricing-health]` | +| `pricing-promotions/ecom-pricing-*.md` support files | support | loaded by the pricing orchestrator or linked recipes | +| `ecom-shipping.md` | category-doc + dispatcher | WixREADME portal index; shipping setup and rate/coverage optimization | +| `shipping/ecom-shipping-setup-rates.md` | promotion | shipping dispatch `[intent:setup-rates]` | +| `shipping/ecom-shipping-setup-regions.md` | promotion | shipping dispatch `[intent:setup-regions]` | +| `shipping/ecom-shipping-setup-pickup.md` | promotion | shipping dispatch `[intent:setup-pickup]` | +| `shipping/ecom-shipping-free-shipping.md` | promotion | shipping dispatch `[intent:free-shipping]`; also loaded by run-a-sale | +| `shipping/ecom-shipping-optimize-rates.md` | promotion | shipping dispatch `[intent:optimize-rates / rate-incorrect]` | +| `shipping/ecom-shipping-fix-coverage.md` | promotion | shipping dispatch `[intent:fix-coverage]` | +| `shipping/ecom-shipping-api.md` | support | inline API reference for Shipping Options and Delivery Profiles | +| `ecom-checkout.md` | category-doc + dispatcher | WixREADME portal index; live checkout/cart setup and troubleshooting | +| `checkout/ecom-checkout-reduce-abandonment.md` | promotion | checkout dispatch `[intent:reduce-abandonment]`; also loaded by run-a-sale ABANDONED_CART branch | +| `checkout/ecom-checkout-troubleshoot-dropoff.md` | promotion | checkout dispatch `[intent:troubleshoot-checkout]` | +| `checkout/ecom-checkout-agentic-readiness.md` | promotion | checkout dispatch `[intent:agentic]` | +| `checkout/ecom-checkout-store-health.md` | promotion | checkout dispatch `[intent:store-health]` | +| `ecom-abandoned-carts.md` | category-doc + dispatcher | WixREADME portal index; recovery/recapture after checkout abandonment | +| `abandoned-carts/ecom-abandoned-carts-recover-email.md` | promotion | abandoned-carts dispatch `[intent:recover-email]` | +| `abandoned-carts/ecom-abandoned-carts-recovery-link.md` | promotion | abandoned-carts dispatch `[intent:recovery-link]` | +| `abandoned-carts/ecom-abandoned-carts-troubleshoot-recovery.md` | promotion | abandoned-carts dispatch `[intent:troubleshoot-recovery]` | +| `abandoned-carts/ecom-abandoned-carts-recovery-health.md` | promotion | abandoned-carts dispatch `[intent:recovery-health]` | +| `ecom-fulfillment.md` | category-doc + dispatcher | WixREADME portal index; post-purchase fulfillment and shipping-document routing | +| `fulfillment/ecom-fulfillment-fulfill-orders.md` | promotion | fulfillment dispatch `[intent:fulfill-order / update-tracking / partial-fulfillment]` | +| `fulfillment/ecom-fulfillment-bulk-fulfill-orders.md` | promotion | fulfillment dispatch `[intent:bulk-fulfill]` | +| (shipping labels) | Dashboard | fulfillment dispatch `[intent:shipping-labels]`; no public API route in this repo | +| (invoice / packing slip) | API route | fulfillment dispatch `[intent:order-invoice]`; eCommerce Orders Invoice API | +| `ecom-orders.md` | category-doc + dispatcher | WixREADME portal index; order lookup + lifecycle routing | +| `orders/ecom-orders-cancel-order.md` | promotion | orders dispatch `[intent:cancel-order]` — `POST /ecom/v1/orders/{id}/cancel` | +| (search / get / counts / pending) | API route | orders main-file routes — `POST /ecom/v1/orders/search`, `GET /ecom/v1/orders/{id}` | +| (approve / return / manual-order / contact / notifications) | Dashboard / unverified | orders handoffs — not authored as skills until the public method is verified | diff --git a/skills/wix-manage/references/ecommerce/tax/ecom-tax-audit.md b/skills/wix-manage/references/ecommerce/tax/ecom-tax-audit.md new file mode 100644 index 00000000..e072dfb5 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/tax/ecom-tax-audit.md @@ -0,0 +1,63 @@ +--- +name: "Tax: Audit Setup" +description: Read-only audit of the site's current tax configuration. Lists available calculators, all tax regions with their calculatorId + inclusive/exclusive setting, all tax groups, all Manual rate mappings, Avalara credentials (if any), and VAT settings (if any). No writes. Triggers on "audit my taxes", "review my tax setup", "show my tax config". +--- + +# Audit Tax Setup + +Read-only diagnostic. No writes — the fix lives in the configure/switch promotions once gaps are identified. + + +## What to query (parallel — TPA-public reads only) + +Run these in parallel; they don't depend on each other: + +``` +CallWixSiteAPI(GET /billing/v1/list-tax-calculators) +CallWixSiteAPI(POST /billing/v1/tax-regions/query, { query: { paging: { limit: 100 } } }) +CallWixSiteAPI(POST /billing/v1/tax-groups/query, { query: { paging: { limit: 100 } } }) +CallWixSiteAPI(POST /billing/v1/tax-groups/list-default-tax-groups, {}) +CallWixSiteAPI(POST /billing/v1/manual-tax-mappings/query, { query: { paging: { limit: 500 } } }) +``` + +Notes: +- `manual-tax-mappings/query` returns Manual-calculator rate mappings only. Avalara regions don't have mappings. +- **Not in this audit (no TPA-public API):** Avalara credentials state, VAT-specific tax-settings (OSS/reverse-charge flags). The merchant has to check those in the **Wix Dashboard → Settings → Taxes**. The audit output can recommend that as a manual follow-up. + +## How to interpret and format + +Build a single audit table for the merchant. One row per region: + +| Region | Calculator | Inclusive | Groups mapped | Rates | Issues | +|---|---|---|---|---|---| +| / | Manual \| Avalara | yes \| no | of groups | | | + +Cross-correlate: +- For each `taxRegion`, look up its `calculatorId` against the `list-tax-calculators` response to label it Manual / Avalara. +- For Manual regions, count how many `manualTaxMappings` exist for that `taxRegionId`. Show actual rates per group. +- For Avalara regions, show "Avalara — live calculation". + +Flag in **Issues** column: +- **No groups mapped** — Manual region with zero `manualTaxMappings` → tax will be 0%. Recommend `ecom-tax-configure` Steps 3-4. +- **Inclusive risk** — `taxIncludedInPrice: false` for an EU region (consumer-law violation). Recommend patching the region. +- **Duplicate** — multiple active regions for the same `country` + `subdivision`. Recommend deleting the older. +- **Stale** — region's `updated_date` > 365 days ago and rates change frequently in that jurisdiction. +- **Avalara without credentials** — region has Avalara `calculatorId` but `GET /billing/v1/avalara-tax-credentials` returns 404 → calculation will fail at checkout. Critical. +- **US partial coverage** — US merchant with regions for only some states. Surface the gap. +- **EU partial coverage** — EU merchant with OSS enabled in `TaxSettings` but missing regions for countries they ship to. + +End with a one-line summary: + +> "Regions: **** · Calculators in use: **** · Groups: **** · Mappings: **** · Inclusive: **** · Issues: ****." + +If issues exist, list each with the recommended next promotion to fix: +- "Missing Manual rate for region " → `ecom-tax-configure` +- "Avalara without credentials" → `ecom-tax-avalara` +- "Switch from Manual → Avalara" → `ecom-tax-switch-calculator` +- "EU region without inclusive pricing" → `ecom-tax-eu-vat` (or PATCH the region directly) + +## Guardrails (inline) + +- **Read-only.** No POST/PATCH/DELETE in this recipe. If the merchant says "fix it", re-dispatch to the appropriate configure/switch promotion. +- **No legal advice.** This recipe reports configuration, not whether the rates are *correct for the merchant's tax obligations*. That's an accountant's job. +- **Paging.** If `tax-regions/query` returns 100+ regions or `manualTaxMappings/query` returns 500+ mappings, paginate with cursors. Don't truncate silently. diff --git a/skills/wix-manage/references/ecommerce/tax/ecom-tax-avalara.md b/skills/wix-manage/references/ecommerce/tax/ecom-tax-avalara.md new file mode 100644 index 00000000..d79e34be --- /dev/null +++ b/skills/wix-manage/references/ecommerce/tax/ecom-tax-avalara.md @@ -0,0 +1,87 @@ +--- +name: "Tax: Configure (Avalara)" +description: Avalara setup — DASHBOARD-ONLY. The Wix Avalara credentials API (`/billing/v1/avalara-tax-credentials`) and the Avalara address-validation API (`/billing/v1/validate-taxable-address`) are NOT TPA-public, so the MCP cannot wire up Avalara directly. This skill instructs the merchant to install/configure Avalara via the Wix Dashboard, then routes the configurable parts (regions + groups) to TPA-public APIs. +--- + +# Configure Tax (Avalara) + +**🚫 The Avalara credentials API is not TPA-public.** Wix Avalara is exposed via a Wix-internal SPI (Tax Calculation Integration Service Plugin) and a dashboard onboarding flow. The MCP **cannot** create or update Avalara credentials, validate addresses against Avalara, or directly toggle Avalara-as-the-calculator from the API. What the merchant must do via the **Wix Dashboard**: + +1. **Install the Avalara app** (Wix App Market → search "Avalara"). +2. **Onboard via the Avalara setup wizard** — supply account ID, license key, company code, company address. This provisions Avalara as a tax calculator on the site. +3. **Activate Avalara per region** in the dashboard's Tax settings (or use the API steps below to create regions bound to Avalara's `calculatorId` once Avalara is installed). + +The merchant must complete those dashboard steps **before** this recipe's API steps work. + +## What this recipe DOES via TPA-public APIs + +Once Avalara is installed via the dashboard, we can use `GET /billing/v1/list-tax-calculators` to obtain Avalara's `calculatorId`, then create tax regions bound to that calculatorId. No `manual-tax-mappings` are needed for Avalara regions — Avalara handles rate lookup. + +## APIs used (TPA-public only) +- `GET /billing/v1/list-tax-calculators` — discover Avalara's `calculatorId` (only present if the merchant installed Avalara via the dashboard). +- `POST /billing/v1/tax-regions` — create tax regions bound to Avalara's `calculatorId`. +- `POST /billing/v1/calculate-tax` — sanity-check a calculation. + +## Step 1 — Confirm Avalara is installed + +``` +CallWixSiteAPI( + url: "https://www.wixapis.com/billing/v1/list-tax-calculators", + method: "GET" +) +``` + +Look for an entry identifying Avalara in the response. If absent, the merchant hasn't installed Avalara via the dashboard yet — **stop** and tell the merchant: "Avalara isn't installed on this site. Install via Wix App Market → search 'Avalara' and complete onboarding. Then re-run this." Optionally re-dispatch to `ecom-tax-configure` for a Wix-Manual setup in the meantime. + +If Avalara is present, capture its `calculatorId`. + +## Step 2 — Create tax regions bound to Avalara + +For each country the merchant ships to under Avalara: + +``` +CallWixSiteAPI( + url: "https://www.wixapis.com/billing/v1/tax-regions", + method: "POST", + body: { + "country": "", + "calculatorId": "", + "taxIncludedInPrice": + } +) +``` + +`taxIncludedInPrice` defaults same as `ecom-tax-configure` Step 2 (US/CA exclusive; EU/UK/AU/NZ/JP inclusive). Watch for `CALCULATOR_IS_NOT_SUPPORTED_FOR_THIS_TAX_REGION` (428) — Avalara may not cover every country; for those, fall back to a Manual region. + +**Do NOT create `manual-tax-mappings`** for Avalara regions — Avalara handles its own rate lookup. + +## Step 3 — Sanity-check via CalculateTax + +``` +CallWixSiteAPI( + url: "https://www.wixapis.com/billing/v1/calculate-tax", + method: "POST", + body: { + "estimateTaxRequestDetails": { + "lineItems": [{ + "taxGroupId": "", + "price": { "amount": "100.00", "currency": "" }, + "addressIndex": 0 + }], + "addresses": [{ "country": "", "subdivision": "" }] + } + } +) +``` + +The returned tax amount is what Avalara would charge. Surface it to the merchant. + +## Step 4 — Confirm to merchant + +> "Avalara confirmed installed · **N** regions configured to use Avalara · Live calculations route to Avalara. Existing Manual regions remain — keep them or switch them via the Switch Tax Calculator recipe." + +## Guardrails (inline) + +- **Dashboard prerequisite.** This recipe requires Avalara already installed via the merchant's Wix Dashboard. The Avalara credentials/onboarding API is not TPA-public; the MCP cannot create Avalara accounts or store credentials. +- **No address pre-flight from the API.** The validate-taxable-address endpoint is also not TPA-public. If a merchant's ship-from address is invalid in Avalara, calculations will fail later — there's no API-level pre-flight; the dashboard handles validation at install time. +- **Don't blanket-replace Manual regions.** Switching an existing Manual region to Avalara requires `PATCH /billing/v1/tax-regions/{id}` with the new `calculatorId` — existing `manual-tax-mappings` for that region become inert (Avalara doesn't use them). Confirm explicitly before patching live regions. diff --git a/skills/wix-manage/references/ecommerce/tax/ecom-tax-configure.md b/skills/wix-manage/references/ecommerce/tax/ecom-tax-configure.md new file mode 100644 index 00000000..64028fdb --- /dev/null +++ b/skills/wix-manage/references/ecommerce/tax/ecom-tax-configure.md @@ -0,0 +1,144 @@ +--- +name: "Tax: Configure (Wix Manual)" +description: Sets up tax using Wix's Manual calculator — discovers available calculators, creates tax regions with the Manual calculatorId, defines tax groups, and creates per-(region, group) rate mappings. Default recipe for the `[intent:configure]` dispatch tag. Triggers on "set up tax", "configure sales tax", "do I need to charge tax". +--- + +# Configure Tax (Wix Manual) + +Baseline tax setup using Wix's built-in Manual calculator. Dispatcher routes here for `[intent:configure]` when neither `calculator:AVALARA` nor `region:EU` context tags match. EU merchants go to `ecom-tax-eu-vat` instead; merchants already on Avalara go to `ecom-tax-avalara`. + + +## Prerequisites +- A Wix store with a payment method connected. +- MerchantContext loaded (`siteData.country`, `siteData.currency`). + +## APIs used +- `GET /billing/v1/list-tax-calculators` — discover the Manual calculator's `calculatorId`. +- `POST /billing/v1/tax-regions` — create a region for the merchant's country. +- `POST /billing/v1/tax-groups` — create a tax group ("Standard"). +- `POST /billing/v1/manual-tax-mappings` — assign a rate to the (region, group) pair (this is where the actual rate is stored for the Manual calculator). +- `POST /billing/v1/calculate-tax` — optional, to sanity-check rates before going live. + +## Step 1 — Discover the Manual calculator's `calculatorId` + +Wix returns all available calculators including the built-in Manual one. Capture the `calculatorId` for `MANUAL` (the exact identifier value comes from this response — do not hardcode). + +``` +CallWixSiteAPI( + url: "https://www.wixapis.com/billing/v1/list-tax-calculators", + method: "POST", + body: {} +) +``` + +From the response, locate the Manual calculator and capture its `calculatorId`. If only Avalara appears in the list with the merchant already onboarded, **stop and re-dispatch** to `ecom-tax-avalara`. + +## Step 2 — Create a tax region for the merchant's country + +``` +CallWixSiteAPI( + url: "https://www.wixapis.com/billing/v1/tax-regions", + method: "POST", + body: { + "country": "", + "calculatorId": "", + "taxIncludedInPrice": + } +) +``` + +**`taxIncludedInPrice` defaults by region:** +- US / CA → `false` (tax-exclusive — added at checkout). +- AU / NZ / JP / IN / GB → `true` (tax-inclusive — already in displayed price). +- Other → ask the merchant. + +The endpoint may return these errors (handle, don't retry blindly): +- `ALREADY_EXISTS` (409) — there's already a region for this country; either update it or use the existing one. +- `CALCULATOR_ID_NOT_FOUND` (404) — Step 1 returned a stale/invalid `calculatorId`; re-list. +- `INVALID_SUBDIVISION_FORMAT` / `SUBDIVISIONS_NOT_SUPPORTED_FOR_COUNTRY` (400) — subdivision string is wrong format or the country doesn't support per-state regions. +- `CALCULATOR_IS_NOT_SUPPORTED_FOR_THIS_TAX_REGION` (428) — the calculator can't be used in this country. + +Capture `taxRegion.id` from the success response. + +## Step 3 — Create a tax group + +A Wix store also has a "system-defined" all-products tax group available via `POST /billing/v1/tax-groups/list-default-tax-groups` — but for custom rates, create your own group: + +``` +CallWixSiteAPI( + url: "https://www.wixapis.com/billing/v1/tax-groups", + method: "POST", + body: { "name": "Standard" } +) +``` + +Capture `taxGroup.id`. For richer taxonomies (Food, Digital, Reduced rate), create multiple groups now. + +## Step 4 — Create the (region, group) → rate mapping + +This is where the actual rate lives in the Manual calculator. `manualTaxMapping` ties a `taxRegionId` + `taxGroupId` + the `taxRate` (and optional jurisdiction labels for display). + +``` +CallWixSiteAPI( + url: "https://www.wixapis.com/billing/v1/manual-tax-mappings", + method: "POST", + body: { + "taxGroupId": "", + "taxRegionId": "", + "taxRate": "", + "taxType": "", + "taxName": "