@wix/agent-skills 1.0.0

package/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md

@@ -0,0 +1,136 @@
+---
+name: "CMS eCommerce Catalog Integration"
+description: The recommended way to sell existing CMS collection items (tickets, bookings, memberships) through Wix checkout. Add the CATALOG plugin to convert any CMS collection into purchasable products with cart and payment integration.
+---
+# CMS eCommerce Catalog Integration
+
+This recipe documents how to convert CMS collections into sellable product catalogs that integrate with Wix eCommerce (cart, checkout, orders).
+
+## Overview
+
+Converting a CMS collection to a catalog enables:
+- Items in the collection become purchasable products
+- Integration with Wix Cart and Checkout APIs
+- Real-time price and availability from your CMS data
+
+## Prerequisites
+
+Your collection needs these fields (or mappable equivalents):
+- **Name field** (TEXT) - Product display name
+- **Price field** (NUMBER) - Product price
+
+Optional catalog fields:
+- **Description** (TEXT) - Product description
+- **Image** (IMAGE) - Product image
+- **URL** (URL) - Product link
+- **Quantity** (NUMBER) - Inventory quantity
+
+## Step 1: Add CATALOG Plugin to Collection
+
+### API Endpoint
+
+```
+POST https://www.wixapis.com/wix-data/v2/collections/add-plugin
+```
+
+### Example: Convert Collection with Custom Field Names
+
+```json
+{
+  "dataCollectionId": "Products",
+  "plugin": {
+    "type": "CATALOG",
+    "catalogOptions": {
+      "name": "title",
+      "price": "price",
+      "description": "description"
+    }
+  }
+}
+```
+
+### Example: Full Catalog with All Optional Fields
+
+```json
+{
+  "dataCollectionId": "Products",
+  "plugin": {
+    "type": "CATALOG",
+    "catalogOptions": {
+      "name": "itemName",
+      "price": "itemPrice",
+      "description": "itemDescription",
+      "image": "itemImage",
+      "url": "itemUrl",
+      "quantity": "itemQuantity"
+    }
+  }
+}
+```
+
+## Step 2: Verify eCommerce App is Installed
+
+Most Wix sites with Stores, Bookings, or similar apps already have eCommerce installed. Check by querying the Cart API:
+
+```
+POST https://www.wixapis.com/ecom/v1/carts
+```
+
+## Step 3: Use Catalog Items in Cart
+
+### CMS App ID (for catalogReference)
+
+```
+e593b0bd-b783-45b8-97c2-873d42aacaf4
+```
+
+### Add CMS Catalog Item to Cart
+
+```
+POST https://www.wixapis.com/ecom/v1/carts/{cartId}/add-to-cart
+```
+
+```json
+{
+  "lineItems": [
+    {
+      "catalogReference": {
+        "appId": "e593b0bd-b783-45b8-97c2-873d42aacaf4",
+        "catalogItemId": "<cms-item-id>"
+      },
+      "quantity": 1
+    }
+  ]
+}
+```
+
+## Removing CATALOG Plugin
+
+```
+POST https://www.wixapis.com/wix-data/v2/collections/delete-plugin
+```
+
+```json
+{
+  "dataCollectionId": "Products",
+  "pluginType": "CATALOG"
+}
+```
+
+## Differences from Wix Stores
+
+| Feature | CMS Catalog | Wix Stores |
+|---------|-------------|------------|
+| Product management | CMS collections | Stores dashboard |
+| Variants | Manual (separate items) | Built-in variant system |
+| Inventory tracking | Manual via quantity field | Automatic |
+| Product options | Not supported | Full support |
+| Discounts | Manual price changes | Built-in discount system |
+
+CMS Catalogs are best for simple product catalogs. For complex eCommerce needs, consider Wix Stores.
+
+## See Also
+
+- [CMS Schema Management](cms-schema-management.md)
+- [CMS Data Operations](cms-data-items-crud.md)
+- [Wix Cart API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/introduction)

package/skills/wix-manage/references/cms/cms-references-and-relationships.md

@@ -0,0 +1,160 @@
+---
+name: "CMS References And Relationships"
+description: "Add, replace, or remove items from MULTI_REFERENCE fields. Use insert-references, replace-references, remove-references endpoints. Required for managing multi-reference relationships - these CANNOT be set via regular insert/update/patch operations. Also covers single references and querying with expanded references."
+---
+# CMS References & Relationships
+
+This recipe covers linking CMS collections together using reference fields.
+
+## Prerequisites
+
+1. Wix CMS enabled on the site
+2. At least two collections to link together
+3. API access with CMS permissions
+
+## Required APIs
+
+- **Collections API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction)
+- **Data Items API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction)
+
+## Reference Types
+
+| Type | Field Type | Relationship | Example |
+|------|------------|--------------|---------|
+| Single Reference | `REFERENCE` | One-to-one, Many-to-one | Product → Category |
+| Multi-Reference | `MULTI_REFERENCE` | One-to-many, Many-to-many | Product → Tags |
+
+## Add a Single Reference Field
+
+**Endpoint**: `POST /wix-data/v2/collections/create-field`
+
+```bash
+curl -X POST \
+'https://www.wixapis.com/wix-data/v2/collections/create-field' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-d '{
+  "dataCollectionId": "Products",
+  "field": {
+    "key": "category",
+    "displayName": "Category",
+    "type": "REFERENCE",
+    "typeMetadata": {
+      "reference": {
+        "referencedCollectionId": "Categories"
+      }
+    }
+  }
+}'
+```
+
+## Add a Multi-Reference Field
+
+**Endpoint**: `POST /wix-data/v2/collections/create-field`
+
+```bash
+curl -X POST \
+'https://www.wixapis.com/wix-data/v2/collections/create-field' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-d '{
+  "dataCollectionId": "Products",
+  "field": {
+    "key": "tags",
+    "displayName": "Tags",
+    "type": "MULTI_REFERENCE",
+    "typeMetadata": {
+      "multiReference": {
+        "referencedCollectionId": "Tags",
+        "referencingFieldKey": "products",
+        "referencingDisplayName": "Products"
+      }
+    }
+  }
+}'
+```
+
+## Insert Multi-Reference Links
+
+**Endpoint**: `POST /wix-data/v2/bulk/items/insert-references`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "dataItemReferences": [
+    {
+      "referringItemId": "product-item-id",
+      "referringItemFieldName": "tags",
+      "referencedItemId": "tag-1-item-id"
+    },
+    {
+      "referringItemId": "product-item-id",
+      "referringItemFieldName": "tags",
+      "referencedItemId": "tag-2-item-id"
+    }
+  ],
+  "returnEntity": true
+}
+```
+
+## Replace All References
+
+**Endpoint**: `POST /wix-data/v2/items/replace-references`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "referringItemId": "product-item-id",
+  "referringItemFieldName": "tags",
+  "newReferencedItemIds": ["new-tag-1-id", "new-tag-2-id", "new-tag-3-id"]
+}
+```
+
+> **Note**: To remove all references, pass an empty array for `newReferencedItemIds`.
+
+## Remove References (Bulk)
+
+**Endpoint**: `POST /wix-data/v2/bulk/items/remove-references`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "dataItemReferences": [
+    {
+      "referringItemId": "product-id-1",
+      "referringItemFieldName": "tags",
+      "referencedItemId": "tag-to-remove-id"
+    }
+  ]
+}
+```
+
+## Query with Referenced Items Expanded
+
+**Endpoint**: `POST /wix-data/v2/items/query`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "query": {
+    "filter": {
+      "inStock": true
+    }
+  },
+  "includeReferencedItems": ["category", "tags"]
+}
+```
+
+## Reference Query Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$eq` | Exact match (single reference) | `{ "category": "id" }` |
+| `$hasSome` | Has at least one of | `{ "tags": { "$hasSome": ["id1", "id2"] } }` |
+| `$hasAll` | Has all of | `{ "tags": { "$hasAll": ["id1", "id2"] } }` |
+
+## Related Documentation
+
+- [Data Items API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction)
+- [Collections API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction)
+- [CMS Schema Management Recipe](cms-schema-management.md)

package/skills/wix-manage/references/cms/cms-schema-management.md

@@ -0,0 +1,143 @@
+---
+name: "CMS Schema Management"
+description: Create and modify CMS collection structures. Covers listing collections, creating collections with fields, adding/removing fields, and updating collection settings.
+---
+# CMS Schema Management
+
+This recipe covers managing the structure (schema) of Wix CMS collections using the REST API.
+
+## Prerequisites
+
+1. Wix CMS enabled on the site
+2. API access with CMS permissions (Manage Data Collections scope)
+
+## Required APIs
+
+- **Collections API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction)
+
+## List All Collections
+
+**Lightweight listing (recommended for existence checks)**:
+```bash
+curl -X GET \
+'https://www.wixapis.com/wix-data/v2/collections?fields=id' \
+-H 'Authorization: <AUTH>'
+```
+
+**Full listing (includes all field schemas)**:
+```bash
+curl -X GET \
+'https://www.wixapis.com/wix-data/v2/collections' \
+-H 'Authorization: <AUTH>'
+```
+
+**Collection Types**: `NATIVE` (user-created), `WIX_APP` (Wix app collections), `BLOCKS_APP`, `EXTERNAL`
+
+## Get Collection Schema
+
+**Endpoint**: `GET /wix-data/v2/collections/{collectionId}`
+
+```bash
+curl -X GET \
+'https://www.wixapis.com/wix-data/v2/collections/Products' \
+-H 'Authorization: <AUTH>'
+```
+
+## Create a New Collection
+
+**Endpoint**: `POST /wix-data/v2/collections`
+
+```json
+{
+  "collection": {
+    "id": "Products",
+    "displayName": "Products",
+    "fields": [
+      {"key": "title", "displayName": "Title", "type": "TEXT", "required": true},
+      {"key": "price", "displayName": "Price", "type": "NUMBER"},
+      {"key": "description", "displayName": "Description", "type": "TEXT"},
+      {"key": "inStock", "displayName": "In Stock", "type": "BOOLEAN"}
+    ],
+    "permissions": {
+      "insert": "ADMIN",
+      "update": "ADMIN",
+      "remove": "ADMIN",
+      "read": "ANYONE"
+    }
+  }
+}
+```
+
+## Add a Field to Existing Collection
+
+**Endpoint**: `POST /wix-data/v2/collections/create-field`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "field": {
+    "key": "sku",
+    "displayName": "SKU",
+    "type": "TEXT",
+    "description": "Product SKU code"
+  }
+}
+```
+
+## Delete a Field from Collection
+
+> **Warning**: This permanently deletes all data stored in this field across all items.
+
+**Endpoint**: `POST /wix-data/v2/collections/delete-field`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "fieldKey": "sku"
+}
+```
+
+## Update Collection Settings
+
+**Endpoint**: `PATCH /wix-data/v2/collections/{collectionId}`
+
+```json
+{
+  "dataCollection": {
+    "id": "Products",
+    "displayName": "Product Catalog"
+  }
+}
+```
+
+## Field Types Reference
+
+| Type | Description | Example Value |
+|------|-------------|---------------|
+| `TEXT` | String | `"Hello World"` |
+| `NUMBER` | Numeric | `99.99` |
+| `BOOLEAN` | True/false | `true` |
+| `DATE` | Date only | `"2024-01-15"` |
+| `DATETIME` | Date and time | `{ "$date": "2024-01-15T10:00:00.000Z" }` |
+| `IMAGE` | Image reference | `"wix:image://v1/..."` |
+| `URL` | Web URL | `"https://example.com"` |
+| `RICH_TEXT` | HTML content | `"<p>Rich text</p>"` |
+| `ARRAY_STRING` | Array of strings | `["tag1", "tag2"]` |
+| `OBJECT` | JSON object | `{"key": "value"}` |
+| `REFERENCE` | Single reference | Item ID string |
+| `MULTI_REFERENCE` | Multiple references | Array of IDs |
+
+## Permission Levels
+
+| Role | Description |
+|------|-------------|
+| `ANYONE` | All visitors (including anonymous) |
+| `SITE_MEMBER` | Logged-in site members |
+| `SITE_MEMBER_AUTHOR` | Members who created the item |
+| `ADMIN` | Site admins only |
+
+## Related Documentation
+
+- [Data Collections API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction)
+- [Data Types in Wix Data](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-types-in-wix-data)
+- [CMS Data Items CRUD Recipe](cms-data-items-crud.md)

package/skills/wix-manage/references/contacts/bulk-delete-contacts.md

@@ -0,0 +1,73 @@
+---
+name: "Bulk Delete Contacts"
+description: Deletes multiple contacts using filter-based bulk delete. Covers safe deletion patterns, GDPR compliance, soft delete alternatives, and batch processing strategies.
+---
+# Bulk Delete Contacts
+
+## Description
+Deletes multiple contacts using the Wix Contacts REST API.
+
+All contacts that meet the specified `filter` and `search` criteria are deleted.
+The request should contain a `filter` value or a `search` value, or both.
+To perform a dry run, call [Query Contacts](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/query-contacts) with the intended filter options.
+
+When this method is called, a bulk job is started and the job ID is returned.
+The job might not complete right away, depending on its size.
+The job's status can be retrieved with [Get Bulk Job](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/bulk-job/get-bulk-job).
+
+**IMPORTANT NOTE:** When specific contacts are to be deleted, they should be filtered by id.
+
+## API Endpoint
+`POST https://www.wixapis.com/contacts/v4/bulk/contacts/delete`
+
+## Request Example
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/contacts/v4/bulk/contacts/delete' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "filter": {
+      "info.name.last": "Smith"
+    }
+  }'
+```
+
+## Request Parameters
+
+- `filter` (object, optional): Filter criteria to identify contacts. When specific contacts are to be deleted, filter by `id`.
+- `search` (string, optional): Search query to identify contacts.
+
+**Note:** The request should contain a `filter` value or a `search` value, or both.
+
+## Response
+
+The response includes a `jobId` which can be used to track the bulk job status:
+
+```json
+{
+  "jobId": "00000000-0000-0000-0000-000000000001"
+}
+```
+
+Use the [Get Bulk Job](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/bulk-job/get-bulk-job) endpoint to check the job status.
+
+## Common Errors
+
+The following errors might occur during the bulk processing and will appear in the bulk job:
+
+- `CANNOT_DELETE_SITE_MEMBERS` - Contact is a site member and can't be deleted. Member must be deleted first.
+- `CANNOT_DELETE_CONTACT_WITH_BILLING_SUBSCRIPTION` - Contact has a valid billing subscription and can't be deleted.
+- `CANNOT_DELETE_MEMBER_OWNER_OR_CONTRIBUTOR` - Member is a Wix user and can't be deleted. This can happen only if the request indicated to delete the member.
+- `FAILED_DELETE_CONTACT_AFTER_MEMBER_DELETION` - Member was deleted, but contact was not. This can happen only if the request indicated to delete the member.
+- `FAILED_DELETE_CONTACT` - Contact could not be deleted.
+
+## Permissions Required
+- `CONTACTS.MODIFY`
+- `MEMBERS.MEMBER_DELETE` (if deleting members)
+
+## Related Documentation
+- [Bulk Delete Contacts API Reference](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/bulk-delete-contacts)
+- [Query Contacts](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/query-contacts)
+- [Get Bulk Job](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/bulk-job/get-bulk-job)

package/skills/wix-manage/references/contacts/bulk-label-and-unlabel-contacts.md

@@ -0,0 +1,67 @@
+---
+name: "Bulk Label and Unlabel Contacts"
+description: Adds/removes labels from multiple contacts using Contacts API bulk operations. Covers label creation, contact filtering, batch processing, and rate limit handling.
+---
+# Bulk Label And Unlabel Contacts
+
+## Description
+Adds and removes labels from multiple contacts using the Wix Contacts REST API.
+
+Labels are added to and removed from all contacts that meet the specified `filter` and `search` criteria.
+The request should specify a `filter` value, a `search` value, or both.
+To perform a dry run, call [Query Contacts](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/query-contacts) with the intended filter options.
+
+When this method is used, a bulk job is started and the job ID is returned.
+The job might not complete right away, depending on its size.
+The job's status can be retrieved with [Get Bulk Job](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/bulk-job/get-bulk-job).
+
+**IMPORTANT NOTE:** When specific contacts are to be labeled, they should be filtered by id.
+
+## API Endpoint
+`POST https://www.wixapis.com/contacts/v4/bulk/contacts/add-remove-labels`
+
+## Request Example
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/contacts/v4/bulk/contacts/add-remove-labels' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "filter": {
+      "info.name.first": "John"
+    },
+    "labelKeysToAdd": ["custom.name-john", "custom.name-starts-with-J"],
+    "labelKeysToRemove": ["custom.last-name-smith"]
+  }'
+```
+
+## Request Parameters
+
+- `filter` (object, optional): Filter criteria to identify contacts. When specific contacts are to be labeled, filter by `id`.
+- `search` (string, optional): Search query to identify contacts.
+- `labelKeysToAdd` (array of strings): Array of label keys to add to matching contacts.
+- `labelKeysToRemove` (array of strings): Array of label keys to remove from matching contacts.
+
+**Note:** The request should specify a `filter` value, a `search` value, or both.
+
+## Response
+
+The response includes a `jobId` which can be used to track the bulk job status:
+
+```json
+{
+  "jobId": "00000000-0000-0000-0000-000000000001"
+}
+```
+
+Use the [Get Bulk Job](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/bulk-job/get-bulk-job) endpoint to check the job status.
+
+## Permissions Required
+- `CONTACTS.MODIFY`
+
+## Related Documentation
+- [Bulk Label And Unlabel Contacts API Reference](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/bulk-label-and-unlabel-contacts)
+- [Query Contacts](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/query-contacts)
+- [Get Bulk Job](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/bulk-job/get-bulk-job)
+- [Labels API Reference](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/labels/introduction)