> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections: key concepts

> Essential concepts for working with ButterCMS Collections, including publication workflows, reference architecture, and localization.

## Overview

Collections serve as your structured data foundation — tables of organized content designed for reference by Pages or direct API queries. Collections excel at managing reusable data that supports and enhances your primary content.

**Core characteristics**

* **ID-based retrieval**: Numeric ID identification for precise, efficient data access
* **Reference-oriented**: Designed primarily to be referenced by Pages and other content types
* **Flexible schemas**: Completely customizable field definitions
* **Performance focus**: Optimized for faster querying and smaller response sizes

**Collections vs. Pages**

| Feature                           | Collections | Pages |
| --------------------------------- | ----------- | ----- |
| Components                        | No          | Yes   |
| Repeaters                         | No          | Yes   |
| Form integrations                 | No          | Yes   |
| Identified by                     | Numeric ID  | Slug  |
| Versioning (draft over published) | No          | Yes   |

**Ideal use cases**: Categories and tags, team member directories, product catalogs, location data, any structured reference data.

## Publication states

Collections use draft and published states, with scheduling available via the dashboard.

| State         | Description                                  | API Access                |
| ------------- | -------------------------------------------- | ------------------------- |
| **Draft**     | Available via preview mode only              | `?preview=1` or `?test=1` |
| **Published** | Live via standard endpoints with CDN caching | Standard endpoints        |
| **Scheduled** | Dashboard only — not supported via Write API | Preview until publication |

Collection publication integrates seamlessly with Page and Blog workflows, allowing coordinated releases where Pages reference Collections that publish simultaneously.

## Preview

Preview enables data validation for draft collection items before publication.

Enable preview by adding `preview=1` to API requests (or `test=1` for the `/v2/content/?keys` endpoint and legacy clients):

```bash theme={null}
GET /v2/content/products/?auth_token=TOKEN&preview=1
```

**Validation workflow**:

1. Create or update collection items in draft status
2. Fetch draft items using preview mode
3. Validate data structure, content accuracy, and integration behavior
4. Review how drafts appear when referenced by Pages
5. Publish after validation confirms expected behavior

**Reference preview**: When previewing Pages that reference Collections, use `preview=1` to ensure both the Page draft and referenced Collection drafts are displayed together.

## Reference architecture

Collections serve as both reference targets and reference sources within ButterCMS's content relationship system.

### Collection-to-page references

Collection items can reference Pages using **page slugs**:

```json theme={null}
{
  "featured_page": "landing-page-slug",
  "related_pages": ["guide-1-slug", "guide-2-slug"],
  "product_page": "product-details-slug"
}
```

### Collection-to-collection references

Collection items can reference other collection items using numeric **IDs**:

```json theme={null}
{
  "parent_category": 123,
  "related_products": [456, 789, 101],
  "department": 234,
  "region": 345
}
```

### Managing references

**Adding references**: Provide the appropriate identifier (page slug or numeric ID) in Write API requests. The system validates reference targets during processing.

**Removing references** — use the appropriate empty value:

| Relationship | Empty value                   |
| ------------ | ----------------------------- |
| One-to-one   | `""` (empty string) or `null` |
| One-to-many  | `[]` (empty array) or `null`  |

**PATCH vs PUT behavior**:

* **PATCH**: Omitted reference fields remain unchanged
* **PUT**: Full replacement semantics apply — provide all fields including references

## Reference levels

The `levels` parameter controls reference field depth in Collection API responses.

| Value         | Behavior                                                         |
| ------------- | ---------------------------------------------------------------- |
| `1`           | Reference fields return API URIs only (optimal for listings)     |
| `2` (default) | Reference fields return complete objects                         |
| `3–5`         | Deeper resolution for nested reference chains                    |
| `5` (max)     | Returns URIs for any remaining references beyond specified depth |

**Performance guidelines for Collections**:

* Use `levels=1` for listings or when building dropdown/select options
* Use `levels=2` (default) for individual item display with reference context
* Use `levels=3–5` when displaying items with deep reference chains
* Use `levels=1` for paginated lists to minimize serialization overhead

**Level 1 response** (URIs only):

```json theme={null}
{
  "data": [
    {
      "meta": { "id": 123 },
      "name": "Technology",
      "related_items": ["/v2/content/?keys=categories[_id=456]"],
      "featured_page": ["/v2/pages/product-guides/tech-overview/"]
    }
  ]
}
```

**Level 2+ response** (complete objects):

```json theme={null}
{
  "data": [
    {
      "meta": { "id": 123 },
      "name": "Technology",
      "related_items": [
        { "meta": { "id": 456 }, "name": "Software", "description": "..." }
      ],
      "featured_page": [
        { "slug": "tech-overview", "fields": { "title": "Technology Guide" } }
      ]
    }
  ]
}
```

## Localization

Collections can maintain separate content versions for each configured locale.

**Account configuration**: Locale support must be configured in your ButterCMS account settings before creating multi-language collections.

<Warning>
  Once locales are added to an account, they cannot be removed. Plan your internationalization approach carefully before configuration.
</Warning>

**API integration**:

```bash theme={null}
# Retrieve collection items in Spanish
GET /v2/content/products/?auth_token=TOKEN&locale=es

# Create a localized collection item
POST /v2/content/products/
```

**Field formats**:

* **Single-language**: Direct field values (no localization configured)
* **Multi-language**: Fields nested under locale codes (e.g., `"en"`, `"es"`, `"fr"`)

Reference fields work seamlessly with localization, allowing different reference relationships per language version.

**Common localization use cases**: Product catalogs with regional descriptions, multi-language team directories, locale-specific category systems, multi-language location data.

## Best practices

**Performance**

* Start with `levels=1` for listing operations and increase only when necessary
* Use pagination for large collections to maintain responsive API performance
* Leverage ButterCMS CDN caching for frequently accessed data

**Content architecture**

* Design schemas that accommodate future data requirements
* Create logical reference patterns that support your content relationships
* Use field validation to maintain data quality across collection items

**Localization**

* Maintain consistent reference relationships across locales where appropriate
* Validate localized data to ensure completeness across all configured locales

## Next steps

<CardGroup cols={2}>
  <Card title="Read API — Collections" icon="book-open" href="../../api-reference/collections/retrieve-collection">
    Fetch collection items via the Read API
  </Card>

  <Card title="Write API — Collections" icon="pen" href="../../api-reference/collections/create-collection-item">
    Create and update collection items
  </Card>

  <Card title="Pages — key concepts" icon="file" href="./pages-key-concepts">
    Learn how Pages work with Collections
  </Card>

  <Card title="Request/Response format" icon="code" href="./request-response-format">
    Understand reference level responses
  </Card>
</CardGroup>