Collections: key concepts - ButterCMS Docs

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):

GET /v2/content/products/?auth_token=TOKEN&preview=1

Validation workflow:

Create or update collection items in draft status
Fetch draft items using preview mode
Validate data structure, content accuracy, and integration behavior
Review how drafts appear when referenced by Pages
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:

{
  "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:

{
  "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):

{
  "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):

{
  "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.

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

API integration:

# 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

Read API — Collections

Fetch collection items via the Read API

Write API — Collections

Create and update collection items

Pages — key concepts

Learn how Pages work with Collections

Request/Response format

Understand reference level responses

​Overview

​Publication states

​Preview

​Reference architecture

​Collection-to-page references

​Collection-to-collection references

​Managing references

​Reference levels

​Localization

​Best practices

​Next steps

Read API — Collections

Write API — Collections

Pages — key concepts

Request/Response format

Overview

Publication states

Preview

Reference architecture

Collection-to-page references

Collection-to-collection references

Managing references

Reference levels

Localization

Best practices

Next steps