Skip to main content

​
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
FeatureCollectionsPages
ComponentsNoYes
RepeatersNoYes
Form integrationsNoYes
Identified byNumeric IDSlug
Versioning (draft over published)NoYes
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.
StateDescriptionAPI Access
DraftAvailable via preview mode only?preview=1 or ?test=1
PublishedLive via standard endpoints with CDN cachingStandard endpoints
ScheduledDashboard only — not supported via Write APIPreview 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:
  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: 
{
  "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:
RelationshipEmpty 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.
ValueBehavior
1Reference fields return API URIs only (optimal for listings)
2 (default)Reference fields return complete objects
3–5Deeper 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