From wix-cli
Use when implementing service plugin extensions that inject custom backend logic into existing Wix business solution flows or introduce new flows to Wix sites (eCommerce, Bookings, etc.). Triggers include SPI, service plugin, backend flow, business logic, custom shipping rates, additional fees, tax calculation, checkout validation, discount triggers, gift cards, eCommerce customization, bookings staff sorting.
npx claudepluginhub wix-playground/skills-architecture-test --plugin wix-cliThis skill uses the workspace's default tool permissions.
Creates service plugin extensions for Wix CLI applications. Service plugins are a set of APIs defined by Wix that you can use to inject custom logic into the existing backend flows of Wix business solutions or to introduce entirely new flows to Wix sites.
Builds and reviews Wix CLI app extensions: dashboard pages, modals, plugins, Editor React components, backend APIs, events, service plugins, data collections. Prepares apps for App Market review.
Guides discovery of Wix eCommerce APIs via Playwright UI automation, official docs, and user guidance to build commands/skills for wix-ecom-cowork plugin.
Builds Shopify Functions: serverless Wasm extensions in JS/Rust for discounts, delivery/payment customization, cart validation/transforms, fulfillment constraints, and order routing.
Share bugs, ideas, or general feedback.
Creates service plugin extensions for Wix CLI applications. Service plugins are a set of APIs defined by Wix that you can use to inject custom logic into the existing backend flows of Wix business solutions or to introduce entirely new flows to Wix sites.
When you implement a service plugin, Wix calls your custom functions during specific flows. Common use cases include eCommerce customization (shipping, fees, taxes, validations) and Bookings customization (staff sorting), but service plugins can extend any Wix business solution that exposes SPIs.
Follow these steps in order when creating a service plugin:
ReadFullDocsMethodSchema with the docs URL from the reference to get the exact request/response types — DO NOT write any code until you have the schemasrc/extensions/backend/service-plugins/<service-type>/<plugin-name>/plugin.ts with correct imports and provideHandlers() callextensions.ts with appropriate builder method and unique UUIDsrc/extensions.ts to import and use the new extensionnpx tsc --noEmit to verify TypeScript compilesnpx wix build to verify build succeedsYou MUST read the relevant reference document before implementing a relevant SPI. Each reference contains the correct imports, handler signatures, response structures, and working examples.
| SPI Type | Reference |
|---|---|
| Additional Fees | ADDITIONAL-FEES.md |
| Discount Triggers | DISCOUNT-TRIGGERS.md |
| Gift Cards | GIFT-CARDS.md |
| Shipping Rates | SHIPPING-RATES.md |
| Tax Calculation | TAX-CALCULATION.md |
| Validations | VALIDATIONS.md |
| Bookings Staff Sorting | BOOKINGS-STAFF-SORTING.md |
Service plugins consist of two files that work together. Registration of plugins requires an extension builder file.
src/extensions/backend/service-plugins/
└── {service-type}/
└── {plugin-name}/
├── plugin.ts # Handler logic with provideHandlers()
└── extensions.ts # Builder configuration (id, name, source)
| File | Purpose |
|---|---|
plugin.ts | Contains the service plugin handler logic with provideHandlers() - this is where you implement your custom business logic |
extensions.ts | Contains the service plugin builder configuration with id (GUID), name, source path, and builder-specific optional fields |
All service plugins must include comprehensive data validation:
The handler file (plugin.ts) contains the service plugin logic. It must:
@wix/ecom/service-plugins for eCommerce, @wix/bookings/service-plugins for Bookings)provideHandlers() with an object containing handler functionsrequest and metadataimport { shippingRates } from "@wix/ecom/service-plugins";
shippingRates.provideHandlers({
getShippingRates: async (payload) => {
const { request, metadata } = payload;
// Implement custom logic based on request data
// - request contains cart items, shipping address, etc.
// - metadata contains currency, locale, etc.
return {
shippingRates: [
{
code: "custom-shipping",
title: "Custom Shipping",
logistics: {
deliveryTime: "3-5 business days",
},
cost: {
price: "9.99",
currency: metadata.currency || "USD",
},
},
],
};
},
});
Handler functions are called automatically by Wix when the relevant site action triggers them. Your custom logic should be placed inside each handler function.
When making Wix API calls from service plugins, you must elevate permissions using auth.elevate from @wix/essentials.
import { auth } from "@wix/essentials";
import { items } from "@wix/data";
export const myFunction = async () => {
const elevatedFunction = auth.elevate(items.query);
const elevatedResponse = await elevatedFunction("myCollection");
return elevatedResponse;
};
import { auth } from "@wix/essentials";
import { cart } from "@wix/ecom";
export const myFunction = async () => {
const elevatedFunction = auth.elevate(cart.getCart);
const elevatedResponse = await elevatedFunction("cart-id");
return elevatedResponse;
};
import { auth } from "@wix/essentials";
import { products } from "@wix/stores";
export const myFunction = async () => {
const elevatedFunction = auth.elevate(products.deleteCollection);
const elevatedResponse = await elevatedFunction("collection-id");
return elevatedResponse;
};
Extension registration is MANDATORY and has TWO required steps.
Each service plugin requires an extensions.ts file in its folder with the appropriate builder method for the SPI type:
import { extensions } from "@wix/astro/builders";
export const ecomadditionalfeesMyFees = extensions.ecomAdditionalFees({
id: "{{GENERATE_UUID}}",
name: "My Additional Fees",
source: "./extensions/backend/service-plugins/ecom-additional-fees/my-fees/plugin.ts",
});
CRITICAL: UUID Generation
The id must be a unique, static UUID v4 string. Generate a fresh UUID for each extension - do NOT use randomUUID() or copy UUIDs from examples. Replace {{GENERATE_UUID}} with a freshly generated UUID like "a1b2c3d4-e5f6-7890-abcd-ef1234567890".
All builder methods accept these three fields:
| Field | Type | Description |
|---|---|---|
id | string | Service plugin ID as a GUID. Must be unique across all extensions in the project. |
name | string | The service plugin name (visible in app dashboard when developing an app). |
source | string | Path to the service plugin handler file that contains the plugin logic. |
Builder methods by SPI type and their accepted fields:
| SPI Type | Builder Method | Accepted Fields |
|---|---|---|
| Shipping Rates | ecomShippingRates() | id, name, source, description, learnMoreUrl, dashboardUrl, fallbackDefinitionMandatory, thumbnailUrl |
| Additional Fees | ecomAdditionalFees() | id, name, source |
| Validations | ecomValidations() | id, name, source, validateInCart |
| Discount Triggers | ecomDiscountTriggers() | id, name, source |
| Gift Cards | ecomGiftCards() | id, name, source |
| Payment Settings | ecomPaymentSettings() | id, name, source, fallbackValueForRequires3dSecure |
| Bookings Staff Sorting | bookingsStaffSortingProvider() | id, name, source, methodName, methodDescription, dashboardPluginId |
Only ecomShippingRates() accepts description. Passing unsupported fields to other builders causes TypeScript errors. bookingsStaffSortingProvider() requires methodName and methodDescription fields, and optionally accepts dashboardPluginId.
CRITICAL: After creating the plugin-specific extension file, you MUST read wix-cli-extension-registration and follow the "App Registration" section to update src/extensions.ts.
Without completing Step 2, the service plugin will not be active in the eCommerce system.
To test your service plugin extension: