From 1edbaabcd2232010b43cde2ef0defeddd74aeca3 Mon Sep 17 00:00:00 2001 From: itayhe Date: Fri, 5 Jun 2026 07:41:12 -0700 Subject: [PATCH 01/18] New skills routing --- skills/wix-manage/SKILL.md | 118 +++++---- .../app-installation/skill-audit.md | 11 + .../wix-manage/references/blog/skill-audit.md | 10 + .../references/bookings/skill-audit.md | 16 ++ .../references/calendar/skill-audit.md | 10 + .../wix-manage/references/cms/skill-audit.md | 14 + .../references/contacts/skill-audit.md | 11 + .../references/domains/skill-audit.md | 10 + .../references/ecommerce/ecom-load-context.md | 114 ++++++++ .../references/ecommerce/ecom-pricing.md | 17 ++ .../references/ecommerce/ecom-tax.md | 17 ++ .../ecom-pricing-create-coupon.md} | 0 .../ecom-pricing-create-discount-rule.md} | 0 .../ecom-pricing-default.md | 66 +++++ .../ecom-pricing-flow-bundle-and-save.md} | 4 +- .../ecom-pricing-flow-seasonal-promotion.md} | 4 +- .../ecom-pricing-flow-stock-mover.md} | 6 +- .../ecom-pricing-flow-upsell-boost.md} | 6 +- .../ecom-pricing-goal-clear-inventory.md} | 4 +- .../ecom-pricing-goal-drive-cross-sells.md} | 2 +- .../ecom-pricing-goal-increase-aov.md} | 6 +- .../ecom-pricing-goal-seasonal-revenue.md} | 2 +- ...m-pricing-guardrail-discount-conflicts.md} | 2 +- ...om-pricing-guardrail-margin-protection.md} | 0 .../ecom-pricing-run-a-sale.md} | 24 +- .../ecom-pricing-tracking-api.md} | 0 ...ecom-pricing-troubleshoot-not-applying.md} | 0 .../references/ecommerce/skill-audit.md | 76 ++++++ .../ecommerce/tax/ecom-tax-audit.md | 63 +++++ .../ecommerce/tax/ecom-tax-avalara.md | 87 +++++++ .../ecommerce/tax/ecom-tax-configure.md | 144 ++++++++++ .../ecommerce/tax/ecom-tax-default.md | 40 +++ .../ecommerce/tax/ecom-tax-eu-vat.md | 139 ++++++++++ .../tax/ecom-tax-switch-calculator.md | 85 ++++++ .../tax/ecom-tax-troubleshoot-calc-wrong.md | 98 +++++++ .../references/forms/skill-audit.md | 10 + .../references/get-paid/skill-audit.md | 14 + .../references/media/skill-audit.md | 10 + .../references/pricing-plans/skill-audit.md | 11 + .../references/restaurants/skill-audit.md | 10 + .../references/rich-content/skill-audit.md | 10 + .../references/site-properties/skill-audit.md | 10 + .../references/sites/skill-audit.md | 11 + .../references/stores/skill-audit.md | 21 ++ yaml/wix-manage/ecommerce/documentation.yaml | 245 +++++++++++++----- 45 files changed, 1407 insertions(+), 151 deletions(-) create mode 100644 skills/wix-manage/references/app-installation/skill-audit.md create mode 100644 skills/wix-manage/references/blog/skill-audit.md create mode 100644 skills/wix-manage/references/bookings/skill-audit.md create mode 100644 skills/wix-manage/references/calendar/skill-audit.md create mode 100644 skills/wix-manage/references/cms/skill-audit.md create mode 100644 skills/wix-manage/references/contacts/skill-audit.md create mode 100644 skills/wix-manage/references/domains/skill-audit.md create mode 100644 skills/wix-manage/references/ecommerce/ecom-load-context.md create mode 100644 skills/wix-manage/references/ecommerce/ecom-pricing.md create mode 100644 skills/wix-manage/references/ecommerce/ecom-tax.md rename skills/wix-manage/references/ecommerce/{setup-coupons.md => pricing-promotions/ecom-pricing-create-coupon.md} (100%) rename skills/wix-manage/references/ecommerce/{setup-discount-rules.md => pricing-promotions/ecom-pricing-create-discount-rule.md} (100%) create mode 100644 skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-default.md rename skills/wix-manage/references/ecommerce/{flow-bundle-and-save.md => pricing-promotions/ecom-pricing-flow-bundle-and-save.md} (98%) rename skills/wix-manage/references/ecommerce/{flow-seasonal-promotion.md => pricing-promotions/ecom-pricing-flow-seasonal-promotion.md} (98%) rename skills/wix-manage/references/ecommerce/{flow-stock-mover.md => pricing-promotions/ecom-pricing-flow-stock-mover.md} (97%) rename skills/wix-manage/references/ecommerce/{flow-upsell-boost.md => pricing-promotions/ecom-pricing-flow-upsell-boost.md} (97%) rename skills/wix-manage/references/ecommerce/{goal-clear-inventory.md => pricing-promotions/ecom-pricing-goal-clear-inventory.md} (96%) rename skills/wix-manage/references/ecommerce/{goal-drive-cross-sells.md => pricing-promotions/ecom-pricing-goal-drive-cross-sells.md} (98%) rename skills/wix-manage/references/ecommerce/{goal-increase-aov.md => pricing-promotions/ecom-pricing-goal-increase-aov.md} (96%) rename skills/wix-manage/references/ecommerce/{goal-seasonal-revenue.md => pricing-promotions/ecom-pricing-goal-seasonal-revenue.md} (98%) rename skills/wix-manage/references/ecommerce/{guardrail-discount-conflicts.md => pricing-promotions/ecom-pricing-guardrail-discount-conflicts.md} (98%) rename skills/wix-manage/references/ecommerce/{guardrail-margin-protection.md => pricing-promotions/ecom-pricing-guardrail-margin-protection.md} (100%) rename skills/wix-manage/references/ecommerce/{recommend-ecommerce-strategy.md => pricing-promotions/ecom-pricing-run-a-sale.md} (94%) rename skills/wix-manage/references/ecommerce/{api-recommendation-tracking.md => pricing-promotions/ecom-pricing-tracking-api.md} (100%) rename skills/wix-manage/references/ecommerce/{troubleshoot-discount-not-applying.md => pricing-promotions/ecom-pricing-troubleshoot-not-applying.md} (100%) create mode 100644 skills/wix-manage/references/ecommerce/skill-audit.md create mode 100644 skills/wix-manage/references/ecommerce/tax/ecom-tax-audit.md create mode 100644 skills/wix-manage/references/ecommerce/tax/ecom-tax-avalara.md create mode 100644 skills/wix-manage/references/ecommerce/tax/ecom-tax-configure.md create mode 100644 skills/wix-manage/references/ecommerce/tax/ecom-tax-default.md create mode 100644 skills/wix-manage/references/ecommerce/tax/ecom-tax-eu-vat.md create mode 100644 skills/wix-manage/references/ecommerce/tax/ecom-tax-switch-calculator.md create mode 100644 skills/wix-manage/references/ecommerce/tax/ecom-tax-troubleshoot-calc-wrong.md create mode 100644 skills/wix-manage/references/forms/skill-audit.md create mode 100644 skills/wix-manage/references/get-paid/skill-audit.md create mode 100644 skills/wix-manage/references/media/skill-audit.md create mode 100644 skills/wix-manage/references/pricing-plans/skill-audit.md create mode 100644 skills/wix-manage/references/restaurants/skill-audit.md create mode 100644 skills/wix-manage/references/rich-content/skill-audit.md create mode 100644 skills/wix-manage/references/site-properties/skill-audit.md create mode 100644 skills/wix-manage/references/sites/skill-audit.md create mode 100644 skills/wix-manage/references/stores/skill-audit.md diff --git a/skills/wix-manage/SKILL.md b/skills/wix-manage/SKILL.md index 1507a7d9..8b8ab2b7 100644 --- a/skills/wix-manage/SKILL.md +++ b/skills/wix-manage/SKILL.md @@ -108,69 +108,87 @@ 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. Two categories are fully migrated: **Tax** and **Pricing & promotions**. Shipping/Checkout files remain at the flat root pending their migration. -### [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) +Category description (README-surfaced). Routes to the Tax dispatcher. + +#### [Tax — Default (dispatcher)](references/ecommerce/tax/ecom-tax-default.md) +Picks Avalara / EU-VAT / Wix-Manual / audit / troubleshoot / switch based on the merchant's request + MerchantContext. + +#### 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) + +--- -### [Troubleshoot: Checkout Delivery Drop-off](references/ecommerce/troubleshoot-checkout-delivery-dropoff.md) -**Technical:** Diagnostic tree for delivery step conversion below 65% benchmark. +### Pricing & Promotions category + +#### [Pricing & Promotions](references/ecommerce/ecom-pricing.md) +Category description (README-surfaced). Routes to the Pricing dispatcher. + +#### [Pricing & Promotions — Default (dispatcher)](references/ecommerce/pricing-promotions/ecom-pricing-default.md) +Picks the right Pricing promotion based on the merchant's intent. + +#### 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) +Pricing support files (goal-* / flow-* / guardrail-* / tracking-api) — flat in pricing-promotions/, loaded by the orchestrator, NOT direct entry points + +- [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) +- [Guardrail: Discount Conflicts](references/ecommerce/pricing-promotions/ecom-pricing-guardrail-discount-conflicts.md) +- [Guardrail: Margin Protection](references/ecommerce/pricing-promotions/ecom-pricing-guardrail-margin-protection.md) +- [API: Recommendation Tracking](references/ecommerce/pricing-promotions/ecom-pricing-tracking-api.md) + +
+ +--- + +### Shipping / Checkout (not yet migrated — flat root) + +These files remain at `references/ecommerce/` until the Shipping & fulfillment and Checkout & cart categories are migrated. They are still valid direct entry points today. + +- [Recipe: Apply Shipping Recommendations](references/ecommerce/recipe-apply-shipping-recommendations.md) +- [Setup Store Pickup Location](references/ecommerce/setup-store-pickup-location.md) +- [Setup Shipping Regions](references/ecommerce/setup-shipping-regions.md) +- [Setup Shipping Rates](references/ecommerce/setup-shipping-rates.md) +- [API: Shipping Delivery](references/ecommerce/api-shipping.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) +- [Flow: Fix Coverage Gaps](references/ecommerce/flow-fix-coverage-gaps.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 +- [Troubleshoot: Checkout Delivery Drop-off](references/ecommerce/troubleshoot-checkout-delivery-dropoff.md) +- [Goal: Reduce Cart Abandonment](references/ecommerce/goal-reduce-cart-abandonment.md) — used by orchestrator's ABANDONED_CART branch; will move under Checkout & cart category #### Reference -- [Skill Graph](references/ecommerce/skill-graph.md) - - +- [Skill Graph](references/ecommerce/skill-graph.md) — author docs only, NOT a runtime skill --- diff --git a/skills/wix-manage/references/app-installation/skill-audit.md b/skills/wix-manage/references/app-installation/skill-audit.md new file mode 100644 index 00000000..9427c106 --- /dev/null +++ b/skills/wix-manage/references/app-installation/skill-audit.md @@ -0,0 +1,11 @@ +--- +name: "App Installation — Skill Audit" +description: Per-skill audit table for the app-installation L1 domain. +--- + +# App Installation — Skill Audit + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `install-wix-apps.md` | Apps Installer API | Likely Yes (production legacy) | TBD | Velo (Wix Code) enablement step; common app definition ID lookup | 📦 Legacy flat | +| `list-installed-apps.md` | Apps Installer API | Likely Yes (production legacy) | **Possibly Yes** | If pure list/query → §7.5 candidate (raw API doc may suffice) | 📦 Legacy flat | diff --git a/skills/wix-manage/references/blog/skill-audit.md b/skills/wix-manage/references/blog/skill-audit.md new file mode 100644 index 00000000..0c1c556d --- /dev/null +++ b/skills/wix-manage/references/blog/skill-audit.md @@ -0,0 +1,10 @@ +--- +name: "Blog — Skill Audit" +description: Per-skill audit table for the blog L1 domain. +--- + +# Blog — Skill Audit + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `how-to-create-blog-posts.md` | Blog Posts API + Media Manager + Categories/Tags | Likely Yes (production legacy) | TBD | Multi-API: Ricos rich-content format; image upload pipeline; category/tag assignment; bulk creation | 📦 Legacy flat | diff --git a/skills/wix-manage/references/bookings/skill-audit.md b/skills/wix-manage/references/bookings/skill-audit.md new file mode 100644 index 00000000..61839638 --- /dev/null +++ b/skills/wix-manage/references/bookings/skill-audit.md @@ -0,0 +1,16 @@ +--- +name: "Bookings — Skill Audit" +description: Per-skill audit table for the bookings L1 domain. +--- + +# Bookings — Skill Audit + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `booking-service-policy-setup.md` | Services API (policy fields) | Likely Yes (production legacy) | TBD | Policy field semantics: bookingPolicy, cancellationPolicy, waitlist; cross-field invariants | 📦 Legacy flat | +| `booking-system-integration-gaps.md` | Bookings + eCommerce payment | Likely Yes (production legacy) | TBD | Undocumented patterns: booking ID → catalog item transformation; async payment confirmation flow | 📦 Legacy flat (doc-of-gaps) | +| `bookings-staff-setup.md` | Staff API + Calendar Events | Likely Yes (production legacy) | TBD | **Critical 2-step process**: create staff → assign schedule → create working-hours events. Order matters. | 📦 Legacy flat | +| `create-and-update-booking-services.md` | Services API CRUD | Likely Yes (production legacy) | TBD | Service-type-specific shapes (APPOINTMENT/CLASS/COURSE); pricing config; location setup | 📦 Legacy flat | +| `end-to-end-booking-flow.md` | Services + Time Slots V2 + Bookings + eCommerce | Likely Yes (production legacy) | No | Cross-domain orchestrator (service discovery → availability → booking → payment) | 📦 Legacy flat | +| `external-calendar-integration.md` | OAuth + Calendar sync APIs | Likely Yes (production legacy) | TBD | OAuth flow for Google/Outlook/Apple; bidirectional sync config | 📦 Legacy flat | +| `multi-resource-service-creation.md` | Resources API | Likely Yes (production legacy) | TBD | Resource types + individuals; automatic allocation logic | 📦 Legacy flat | diff --git a/skills/wix-manage/references/calendar/skill-audit.md b/skills/wix-manage/references/calendar/skill-audit.md new file mode 100644 index 00000000..b1617499 --- /dev/null +++ b/skills/wix-manage/references/calendar/skill-audit.md @@ -0,0 +1,10 @@ +--- +name: "Calendar — Skill Audit" +description: Per-skill audit table for the calendar L1 domain. +--- + +# Calendar — Skill Audit + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `configure-default-business-hours.md` | Calendar Events API | Likely Yes (production legacy) | No | **Critical distinction: Calendar Events API (correct) vs Site Properties API (incorrect)** for setting base availability. This is the kind of "wrong API would also have worked but doesn't actually do the thing" trap that justifies a skill. | 📦 Legacy flat | diff --git a/skills/wix-manage/references/cms/skill-audit.md b/skills/wix-manage/references/cms/skill-audit.md new file mode 100644 index 00000000..d0de4b6c --- /dev/null +++ b/skills/wix-manage/references/cms/skill-audit.md @@ -0,0 +1,14 @@ +--- +name: "CMS — Skill Audit" +description: Per-skill audit table for the CMS L1 domain. +--- + +# CMS — Skill Audit + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `cms-data-items-crud.md` | wix-data v2 (items, bulk/items) | Likely Yes (production legacy) | TBD | Bulk insert/update/patch/delete patterns; filter syntax | 📦 Legacy flat | +| `cms-data-operations-extended.md` | wix-data v2 (count, upsert) | Likely Yes (production legacy) | **Possibly Yes** | If pure API summary → §7.5 candidate | 📦 Legacy flat | +| `cms-ecommerce-catalog-integration.md` | wix-data + Stores catalog plugin | Likely Yes (production legacy) | No | **CATALOG plugin pattern** — non-obvious way to convert CMS collections into purchasable items | 📦 Legacy flat | +| `cms-references-and-relationships.md` | wix-data (insert/replace/remove references) | Likely Yes (production legacy) | TBD | **Multi-reference fields can't be set via regular insert/update** — must use dedicated reference endpoints; this is non-obvious | 📦 Legacy flat | +| `cms-schema-management.md` | wix-data Schemas API | Likely Yes (production legacy) | TBD | Collection structure operations + field management | 📦 Legacy flat | diff --git a/skills/wix-manage/references/contacts/skill-audit.md b/skills/wix-manage/references/contacts/skill-audit.md new file mode 100644 index 00000000..07ebf1ce --- /dev/null +++ b/skills/wix-manage/references/contacts/skill-audit.md @@ -0,0 +1,11 @@ +--- +name: "Contacts — Skill Audit" +description: Per-skill audit table for the contacts L1 domain (planned home for the Customers L2). +--- + +# Contacts — Skill Audit + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `bulk-delete-contacts.md` | Contacts API (Bulk Delete) | Likely Yes (production legacy) | TBD | GDPR compliance considerations · soft-delete alternatives · batch sizing | 📦 Legacy flat | +| `bulk-label-and-unlabel-contacts.md` | Contacts API (Labels + Bulk ops) | Likely Yes (production legacy) | TBD | Label creation prerequisite · rate-limit handling · contact-filter patterns | 📦 Legacy flat | diff --git a/skills/wix-manage/references/domains/skill-audit.md b/skills/wix-manage/references/domains/skill-audit.md new file mode 100644 index 00000000..fbfefd33 --- /dev/null +++ b/skills/wix-manage/references/domains/skill-audit.md @@ -0,0 +1,10 @@ +--- +name: "Domains — Skill Audit" +description: Per-skill audit table for the domains L1 domain. +--- + +# Domains — Skill Audit + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `domain-search-and-purchase.md` | Domain Search V2 API | Likely Yes (production legacy) | TBD | Availability checks · TLD filtering · purchase-link generation · connecting domains to Wix sites | 📦 Legacy flat | 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..5a0982f7 --- /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 `tax/ecom-tax-default.md` or in each Tax promotion when it runs. Not here. (Currently Tax APIs aren't TPA-public anyway, so Tax recipes are design docs — see `tax/` and `skill-audit.md`.) +- **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-pricing.md b/skills/wix-manage/references/ecommerce/ecom-pricing.md new file mode 100644 index 00000000..ee5eb5a0 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/ecom-pricing.md @@ -0,0 +1,17 @@ +--- +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 → see **Finance & payments**. + +## Enter this category + +> - [Pricing & promotions recipes](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-default) 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..58faac92 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/ecom-tax.md @@ -0,0 +1,17 @@ +--- +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**. + +## Enter this category + +> - [Tax recipes](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-tax-default) 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 100% rename from skills/wix-manage/references/ecommerce/setup-coupons.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-create-coupon.md 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 100% 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 diff --git a/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-default.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-default.md new file mode 100644 index 00000000..d4b62760 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-default.md @@ -0,0 +1,66 @@ +--- +name: "Pricing & Promotions — Default" +description: Dispatch entry for all Pricing & promotions intents — coupons, discount rules, sales, bundles, ribbons, scheduling, the run-a-sale orchestrator, troubleshooting, and competitive pricing. +--- + +# Pricing & Promotions — Default + +> **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/ecom-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/ecom-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/ecom-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/ecom-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/ecom-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/ecom-pricing-run-a-sale) — tags: `[intent:run-a-sale]` · priority 0 +> - [Boost my business / increase sales](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-run-a-sale) — tags: `[intent:boost-business]` · priority 0 +> - [Seasonal / holiday promotion](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-run-a-sale) — tags: `[intent:seasonal-promo]` · priority 0 +> - [Clearance / move slow stock](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-run-a-sale) — tags: `[intent:clearance]` · priority 0 +> - [Increase AOV (bundle / upsell)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-run-a-sale) — 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/ecom-pricing-troubleshoot-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** + +### 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/ecom-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/flow-bundle-and-save.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-bundle-and-save.md similarity index 98% 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..29200a33 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 @@ -13,8 +13,8 @@ references: # 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) +> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-guardrail-discount-conflicts) +> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-create-discount-rule) 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. 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 98% 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..59e62529 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 @@ -13,8 +13,8 @@ references: # 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) +> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-guardrail-discount-conflicts) +> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-create-discount-rule) 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. 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 97% 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..989f0cfb 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 @@ -16,9 +16,9 @@ references: # 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) +> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-guardrail-discount-conflicts) +> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-guardrail-margin-protection) +> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-create-discount-rule) 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. 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 97% 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..57972924 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 @@ -16,9 +16,9 @@ references: # 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) +> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-guardrail-discount-conflicts) +> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-guardrail-margin-protection) +> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-create-discount-rule) 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. 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 96% 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..bd8a202e 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 @@ -13,10 +13,10 @@ references: # 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) +> - [Flow: Stock Mover](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-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) +> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-guardrail-margin-protection) 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 98% 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..3bef20e0 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 @@ -10,7 +10,7 @@ references: # Goal: Drive Cross-Sells and Product Discovery > **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`: -> - [Flow: Bundle and Save](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-bundle-and-save) +> - [Flow: Bundle and Save](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-flow-bundle-and-save) Promote product discovery and multi-item purchases by creating bundle-based discounts that reward customers for buying across categories or adding complementary items to their cart. 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 96% 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..471ae995 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 @@ -22,15 +22,15 @@ references: # Goal: Increase Average Order Value > **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`: -> - [Flow: Upsell Boost](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-upsell-boost) -> - [Flow: Bundle and Save](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-bundle-and-save) +> - [Flow: Upsell Boost](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-flow-upsell-boost) +> - [Flow: Bundle and Save](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-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 > > **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) +> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-guardrail-margin-protection) 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 98% 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..09cc17e2 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 @@ -10,7 +10,7 @@ references: # Goal: Capitalize on Seasonal Events > **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`: -> - [Flow: Seasonal Promotion](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-seasonal-promotion) +> - [Flow: Seasonal Promotion](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-flow-seasonal-promotion) Capitalize on holidays, cultural events, and seasonal moments to drive revenue spikes through time-limited promotional campaigns. diff --git a/skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-guardrail-discount-conflicts.md similarity index 98% rename from skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-guardrail-discount-conflicts.md index 2a215203..c5b17015 100644 --- a/skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md +++ b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-guardrail-discount-conflicts.md @@ -10,7 +10,7 @@ references: # 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) +> - [Troubleshoot: Discount Not Applying](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-troubleshoot-not-applying) ## When to use this guardrail diff --git a/skills/wix-manage/references/ecommerce/guardrail-margin-protection.md b/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-guardrail-margin-protection.md similarity index 100% rename from skills/wix-manage/references/ecommerce/guardrail-margin-protection.md rename to skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-guardrail-margin-protection.md 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 94% 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..38222c11 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 @@ -25,18 +25,20 @@ references: path: ecommerce/setup-coupons.md load: false --- -# Recommend: eCommerce Strategy +# Run a Sale (Recommend eCommerce Strategy) + +> **Routing note.** Reached via dispatch from [Pricing & Promotions — Default](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-default) 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/ecom-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`: -> - **SEASONAL** → [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-seasonal-revenue) -> - **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) +> - **SEASONAL** → [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-goal-seasonal-revenue) +> - **UPSELL_BOOST** / **SHIPPING** → [Goal: Increase AOV](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-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/ecom-pricing-goal-clear-inventory) +> - **BUNDLE_AND_SAVE** → [Goal: Drive Cross-Sells](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-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) *(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/ecom-pricing-create-coupon) ## EXECUTION RULES — READ BEFORE ANYTHING ELSE @@ -197,10 +199,10 @@ Based on the merchant's request AND the site data, determine which domains to an | Discount goal | Trigger | Load this skill | |---|---|---| -| SEASONAL | Holiday/event/date mentioned | [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-seasonal-revenue) | -| UPSELL_BOOST | "increase AOV", "spend more", "upsell" | [Goal: Increase AOV](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-increase-aov) | -| STOCK_MOVER | "clear inventory", "overstock", "clearance" | [Goal: Clear Inventory](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-clear-inventory) | -| BUNDLE_AND_SAVE | "bundle", "cross-sell", "buy together" | [Goal: Drive Cross-Sells](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-drive-cross-sells) | +| SEASONAL | Holiday/event/date mentioned | [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-goal-seasonal-revenue) | +| UPSELL_BOOST | "increase AOV", "spend more", "upsell" | [Goal: Increase AOV](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-goal-increase-aov) | +| STOCK_MOVER | "clear inventory", "overstock", "clearance" | [Goal: Clear Inventory](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-goal-clear-inventory) | +| BUNDLE_AND_SAVE | "bundle", "cross-sell", "buy together" | [Goal: Drive Cross-Sells](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/ecom-pricing-goal-drive-cross-sells) | | Generic (no clear goal) | "boost sales", ambiguous | Default to SEASONAL if holiday nearby, else UPSELL_BOOST | **For SHIPPING domain — load the same goal as discounts.** Shipping flows (free shipping threshold, rate optimization) serve the same business goals as discount flows. Load the matching discount goal above — it now includes shipping flow references. 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 100% 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 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 100% 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 diff --git a/skills/wix-manage/references/ecommerce/skill-audit.md b/skills/wix-manage/references/ecommerce/skill-audit.md new file mode 100644 index 00000000..5f0c2c3b --- /dev/null +++ b/skills/wix-manage/references/ecommerce/skill-audit.md @@ -0,0 +1,76 @@ +--- +name: "eCommerce — Skill Audit" +description: Per-file status for the ecommerce L1 domain. Rules and conventions are in the `wix-skills-routing-expert` Claude Code skill. +--- + +# eCommerce — Skill Audit + +## L1 loader + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `ecom-load-context.md` | profile/metasite | Yes | No | General site context loader (siteId, country, region, industry, currency, AOV, traffic) | ✅ Active | + +## Category-doc files + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `ecom-tax.md` | n/a | n/a | n/a | Category description + disambiguation labels | ✅ Active | +| `ecom-pricing.md` | n/a | n/a | n/a | Category description + disambiguation labels | ✅ Active | + +## Tax — `tax/` + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `ecom-tax-default.md` | n/a (dispatcher) | n/a | n/a | Tag-match dispatch + worked examples + base recipe fallback | ✅ Active | +| `ecom-tax-configure.md` | `GET /billing/v1/list-tax-calculators` · `POST /billing/v1/tax-regions` · `POST /billing/v1/tax-groups` · `POST /billing/v1/manual-tax-mappings` · `POST /billing/v1/calculate-tax` | Yes | No | 4-step orchestration; rates-in-`manual-tax-mappings` model insight; per-country `taxIncludedInPrice` defaults; US state-level warning | ✅ Active | +| `ecom-tax-avalara.md` | `GET /billing/v1/list-tax-calculators` · `POST /billing/v1/tax-regions` · `POST /billing/v1/calculate-tax` | Partial | No | Dashboard-prerequisite pattern: merchant installs Avalara via Dashboard; recipe binds tax-regions to Avalara's `calculatorId` via TPA-public endpoints | ✅ Active | +| `ecom-tax-eu-vat.md` | `GET /billing/v1/list-tax-calculators` · `POST /billing/v1/tax-regions` (looped) · `POST /billing/v1/tax-groups` · `POST /billing/v1/bulk-create-manual-tax-mappings` · `POST /billing/v1/calculate-tax` | Yes | No | `taxIncludedInPrice` per-region; bulk mappings; don't default to all 27; OSS / reverse-charge surfaced as Dashboard-only | ✅ Active | +| `ecom-tax-switch-calculator.md` | `GET /billing/v1/list-tax-calculators` · `POST /billing/v1/tax-regions/query` · `PATCH /billing/v1/tax-regions/{id}` · `POST /billing/v1/calculate-tax` | Yes | No | Per-region calculatorId model; Manual mappings become inert under Avalara, reactivate on switch-back; revision-handling | ✅ Active | +| `ecom-tax-audit.md` | 5 parallel reads: list-calculators · tax-regions/query · tax-groups/query · list-default-tax-groups · manual-tax-mappings/query | Yes | No | Cross-correlation rules; issue-detection rules; Dashboard follow-up for OSS / Avalara state | ✅ Active | +| `ecom-tax-troubleshoot-calc-wrong.md` | `POST /billing/v1/calculate-tax` · `POST /billing/v1/tax-regions/query` · `POST /billing/v1/manual-tax-mappings/query` | Yes | No | 3-branch diagnostic tree; orders snapshot rates at checkout time; Avalara-issue branch routes merchant to Dashboard | ✅ Active | + +## Pricing & promotions — `pricing-promotions/` + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `ecom-pricing-default.md` | n/a (dispatcher) | n/a | n/a | Dispatch block + cross-category routing notes | ✅ Active | +| `ecom-pricing-create-coupon.md` | Coupons V2 API | Likely Yes | TBD | Coupon-type → spec field mapping; scope targeting; usage limits; conflict-check first | ⏳ Audit pending | +| `ecom-pricing-create-discount-rule.md` | Discount Rules API | Likely Yes | TBD | Multi-step rule construction | ⏳ Audit pending | +| `ecom-pricing-run-a-sale.md` | Coupons + Discount Rules + Recommendations + Catalog Analytics | Likely Yes (tracking URL TBD) | No | Strategy orchestrator: holiday detection, AOV-band tiers, goal classification, decision-conditional support loading | ⏳ Audit pending | +| `ecom-pricing-troubleshoot-not-applying.md` | Coupons + Discount Rules query | Likely Yes | TBD | Diagnostic tree for inactive/non-applying discounts | ⏳ Audit pending | +| `ecom-pricing-goal-seasonal-revenue.md` | (support) | inherits | n/a | SEASONAL goal: KPIs, magnitude tiers, holiday-window logic | ⏳ Audit pending | +| `ecom-pricing-goal-clear-inventory.md` | (support) | inherits | n/a | STOCK_MOVER goal | ⏳ Audit pending | +| `ecom-pricing-goal-increase-aov.md` | (support) | inherits | n/a | UPSELL_BOOST goal | ⏳ Audit pending | +| `ecom-pricing-goal-drive-cross-sells.md` | (support) | inherits | n/a | BUNDLE_AND_SAVE goal | ⏳ Audit pending | +| `ecom-pricing-flow-seasonal-promotion.md` | Discount Rules API | Likely Yes | n/a | SEASONAL flow execution | ⏳ Audit pending | +| `ecom-pricing-flow-upsell-boost.md` | Discount Rules API | Likely Yes | n/a | UPSELL_BOOST flow execution | ⏳ Audit pending | +| `ecom-pricing-flow-bundle-and-save.md` | Discount Rules API | Likely Yes | n/a | Bundle/cross-sell flow | ⏳ Audit pending | +| `ecom-pricing-flow-stock-mover.md` | Discount Rules + Inventory query | Likely Yes | n/a | Stock-mover flow with inventory analysis | ⏳ Audit pending | +| `ecom-pricing-guardrail-discount-conflicts.md` | Coupons + Discount Rules query | Likely Yes | n/a | Conflict detection rules across active promos | ⏳ Audit pending | +| `ecom-pricing-guardrail-margin-protection.md` | Catalog Analytics | TBD | n/a | Margin floor enforcement (15% default) | ⏳ Audit pending | +| `ecom-pricing-tracking-api.md` | `agentic-recommendations` tracking endpoint | TBD | No | Tracking endpoint payload shapes | ⏳ Audit pending | + +## Shipping & checkout — flat at `ecommerce/` root (not migrated) + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `setup-shipping-rates.md` | Shipping Rates API | Likely Yes | TBD | Legacy recipe | 📦 Legacy flat | +| `setup-shipping-regions.md` | Shipping Regions API | Likely Yes | TBD | Legacy recipe | 📦 Legacy flat | +| `setup-store-pickup-location.md` | Pickup / Delivery Profiles | Likely Yes | TBD | Legacy recipe | 📦 Legacy flat | +| `recipe-apply-shipping-recommendations.md` | Shipping + Recommendations | TBD | TBD | Applies AI-generated shipping recs | 📦 Legacy flat | +| `flow-add-free-shipping.md` | Shipping Rates API | Likely Yes | TBD | Free-shipping threshold flow | 📦 Legacy flat | +| `flow-optimize-shipping-rates.md` | Shipping + Catalog Analytics | TBD | TBD | Rate-optimization flow | 📦 Legacy flat | +| `flow-fix-coverage-gaps.md` | Shipping Regions API | Likely Yes | TBD | Coverage-gap remediation flow | 📦 Legacy flat | +| `guardrail-shipping-health.md` | Shipping query | Likely Yes | TBD | Shipping configuration health check | 📦 Legacy flat | +| `guardrail-rate-pricing-sanity.md` | Shipping + Catalog Analytics | TBD | TBD | Rate-vs-AOV sanity | 📦 Legacy flat | +| `goal-reduce-cart-abandonment.md` | (support — abandoned cart) | inherits | n/a | Will move under Checkout & cart when migrated | 📦 Legacy flat | +| `api-shipping.md` | (API reference doc) | inherits | Likely Yes | If just endpoint summaries → dissolve into API-doc URLs per §7.5 | 📦 Legacy flat | +| `troubleshoot-checkout-delivery-dropoff.md` | Checkout + Shipping query | Likely Yes | TBD | Diagnostic for delivery-step conversion < 65% | 📦 Legacy flat | + +## Documentation + +| File name | Wix API Doc | TPA-public? | Claude Redundant | Beyond Wix Docs | Status | +|---|---|---|---|---|---| +| `skill-graph.md` | n/a | n/a | n/a | Mermaid diagram of skill relationships | 📝 Doc | +| `skill-audit.md` (this file) | n/a | n/a | n/a | This audit | 📝 Doc | 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..bf758d9d --- /dev/null +++ b/skills/wix-manage/references/ecommerce/tax/ecom-tax-audit.md @@ -0,0 +1,63 @@ +--- +name: "Audit Tax 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..bf6bc61e --- /dev/null +++ b/skills/wix-manage/references/ecommerce/tax/ecom-tax-avalara.md @@ -0,0 +1,87 @@ +--- +name: "Configure Tax (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..d10aec32 --- /dev/null +++ b/skills/wix-manage/references/ecommerce/tax/ecom-tax-configure.md @@ -0,0 +1,144 @@ +--- +name: "Configure Tax (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": "", + "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/plugins/wix/skills/wix-manage/references/ecommerce/tax/ecom-tax-configure.md b/plugins/wix/skills/wix-manage/references/ecommerce/tax/ecom-tax-configure.md new file mode 100644 index 00000000..d10aec32 --- /dev/null +++ b/plugins/wix/skills/wix-manage/references/ecommerce/tax/ecom-tax-configure.md @@ -0,0 +1,144 @@ +--- +name: "Configure Tax (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": "", - "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/plugins/wix/skills/wix-manage/references/ecommerce/tax/ecom-tax-configure.md b/plugins/wix/skills/wix-manage/references/ecommerce/tax/ecom-tax-configure.md deleted file mode 100644 index d10aec32..00000000 --- a/plugins/wix/skills/wix-manage/references/ecommerce/tax/ecom-tax-configure.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -name: "Configure Tax (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": "