Skip to main content

​
Retention policies

Understanding how ButterCMS retains version history is important for content governance and compliance. Version history helps you recover content and media that have changed, but there are important considerations about what is preserved and for how long.

​
What is retained

​
Automatic version retention

ButterCMS automatically retains version history for your content:
Content typeVersions retainedNotes
PagesAll versionsFull history from creation
CollectionsAll versionsItem-level version tracking
Blog PostsLimitedSimplified versioning model

​
What’s preserved in each version

For each saved version, ButterCMS preserves:
  • Field values - All text, numbers, dates, and other content
  • Media references - Links to images and files in the Media Library
  • Component configurations - Component instances and their settings
  • Reference relationships - Links to other Pages and Collections
  • Metadata - SEO fields, slugs, and other properties
  • Attribution - Who saved and when

​
Content modeling limitations

Important limitation:Version history helps you to recover content and media that have changed. However, if changes are made to the content modeling of a page or collection (i.e., content fields have been added or deleted), only the currently published content fields that have been configured will be available for any version.

​
How schema changes affect history

When you modify your content model (Page Type, Collection, etc.):
Schema changeImpact on historical versions
Field addedHistorical versions won’t have data for this field
Field removedHistorical data for this field won’t be visible
Field type changedHistorical data may not display correctly
Field renamedTreated as remove + add; historical data may be affected
Component schema changedComponent instances in history may be impacted

​
Example: schema change impact

Before schema change: 
Page Type: Landing Page
├── headline (text)
├── body (rich text)
└── cta_text (text)
After adding a field: 
Page Type: Landing Page
├── headline (text)
├── body (rich text)
├── cta_text (text)
└── cta_url (text)  ← New field
Result: Historical versions before the change will show empty/null for cta_url because that field didn’t exist when those versions were saved.

​
Media retention

​
How media references work in history

Version history preserves references to media files, not copies of the files themselves:
ScenarioBehavior
Media still existsHistorical version can display the media
Media was replacedHistorical version shows the new media (same reference)
Media was deletedHistorical version shows broken reference
If you delete a media file from the Media Library, historical versions that referenced that file will no longer be able to display it. The reference is preserved, but the file is gone.

​
Best practice for media

If you need to change an image but preserve access to the old one:
  1. Upload the new image as a new file (don’t replace)
  2. Update the content to use the new image
  3. Keep the old image in the Media Library
This ensures historical versions can still display the original image.

​
Locked versions

Locked versions represent previously Published content that has been superseded by a newer publication. These versions:
  • Can no longer be modified directly
  • Remain accessible in the version history
  • Can be reverted to, restoring that content state

​
Locked version retention

AspectPolicy
StorageLocked versions are retained indefinitely
AccessibilityAlways visible in revision history
RestorationCan be restored at any time
Count limitNo limit on number of locked versions

​
Version state transitions

Draft → Published (becomes Locked when superseded)
                ↓
         Published → New Draft → Published (previous becomes Locked)
                                      ↓
                                 And so on...

Timeline:
v1 (Locked) → v2 (Locked) → v3 (Locked) → v4 (Published) → v5 (Draft)

​
Data retention by plan

​
Enterprise features

Enterprise plans may include additional retention capabilities:
FeatureStandard plansEnterprise
Version historyFull retentionFull retention
Audit logsBasicExtended
Backup frequencyDailyCustom options
Data exportAvailableEnhanced
Contact ButterCMS sales for specific enterprise retention policies and compliance requirements.

​
Compliance considerations

ButterCMS provides a transparent audit trail that documents all content changes and approvals, supporting compliance requirements and making it easy to track the progress of each content piece.

​
Regulatory compliance

For organizations with compliance requirements:
RequirementButterCMS support
Content audit trailFull version history with attribution
Approval documentationWorkflow history preserved
Change trackingWho, what, when for all changes
Data retentionConfigurable with enterprise plans

​
Compliance best practices

  • Document schema changes - Keep a log of content model modifications
  • Export important content - Periodically export critical content for backup
  • Use workflows - Formal approval processes create better audit trails
  • Review retention needs - Align ButterCMS retention with compliance requirements

​
Backup and recovery

​
ButterCMS backup policies

ButterCMS performs regular backups of your content:
Backup typeFrequencyAvailability
Content dataDailyEnterprise feature for restoration
Media filesContinuousCDN-backed storage
ConfigurationOn changeIncluded with content

​
Your responsibility

While ButterCMS maintains backups, consider your own backup strategy:
  • Export content regularly - Use the API to export critical content
  • Document configurations - Keep records of content models and settings
  • Test restoration - Periodically verify you can restore from your backups

​
Best practices for retention

Plan schema changes

Before modifying content models, consider the impact on historical versions

Preserve media

Don’t delete media files that may be referenced by historical content

Document changes

Keep external records of significant schema modifications

Export critical content

Periodically export important content for your own records

​
Retention checklist

For important content:
  • Understand your compliance retention requirements
  • Document all content model changes and their dates
  • Avoid deleting media files that may be needed historically
  • Periodically export critical content
  • Review version history to ensure expected retention
  • Test restoration procedures annually

​
Working with retention limits

​
Strategies for schema changes

When you need to modify your content model:
  1. Plan carefully - Consider all implications before making changes
  2. Communicate timing - Let your team know when changes will occur
  3. Export current state - Backup content before major schema changes
  4. Document the change - Record what changed and why
  5. Test thoroughly - Verify historical content still displays acceptably

​
Managing long-term content

For content with long-term retention needs:
  • Use stable, well-planned content models
  • Minimize schema changes after content is published
  • Consider separate content types for different retention needs
  • Export and archive content that requires permanent preservation

​
Frequently asked questions

ButterCMS retains all version history indefinitely. There is no automatic deletion of historical versions based on time or count.
Individual versions cannot be deleted from the history. The complete version timeline is preserved for audit and recovery purposes.
When content is deleted, its version history is removed. Consider unpublishing rather than deleting if you may need to restore later.
Yes, version histories are included in ButterCMS’s backup systems. Enterprise customers can access enhanced backup and restoration options.
The standard API provides access to current content. For full version history export, contact ButterCMS support.
Existing content data is preserved, but new fields won’t have data in historical versions, and removed fields won’t be visible.