> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: CMS References And Relationships

## Article: CMS References And Relationships

## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/cms/skills/cms-references-and-relationships.md

## Article Content:

# 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.md)
- **Data Items API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction.md)

## 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.md)
- [Collections API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction.md)
- [CMS Schema Management Recipe](https://dev.wix.com/docs/api-reference/business-solutions/cms/skills/cms-schema-management.md)