> ## 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.

# Retention policies

> Understand the retention policies for revision history in ButterCMS, including what's preserved, limitations, and best practices.

# 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 type    | Versions retained | Notes                       |
| --------------- | ----------------- | --------------------------- |
| **Pages**       | All versions      | Full history from creation  |
| **Collections** | All versions      | Item-level version tracking |
| **Blog Posts**  | Limited           | Simplified 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

<Warning>
  **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.
</Warning>

### How schema changes affect history

When you modify your content model (Page Type, Collection, etc.):

| Schema change                | Impact on historical versions                            |
| ---------------------------- | -------------------------------------------------------- |
| **Field added**              | Historical versions won't have data for this field       |
| **Field removed**            | Historical data for this field won't be visible          |
| **Field type changed**       | Historical data may not display correctly                |
| **Field renamed**            | Treated as remove + add; historical data may be affected |
| **Component schema changed** | Component 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:

| Scenario           | Behavior                                                |
| ------------------ | ------------------------------------------------------- |
| Media still exists | Historical version can display the media                |
| Media was replaced | Historical version shows the new media (same reference) |
| Media was deleted  | Historical version shows broken reference               |

<Warning>
  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.
</Warning>

### 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

| Aspect            | Policy                                    |
| ----------------- | ----------------------------------------- |
| **Storage**       | Locked versions are retained indefinitely |
| **Accessibility** | Always visible in revision history        |
| **Restoration**   | Can be restored at any time               |
| **Count limit**   | No 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:

| Feature              | Standard plans | Enterprise     |
| -------------------- | -------------- | -------------- |
| **Version history**  | Full retention | Full retention |
| **Audit logs**       | Basic          | Extended       |
| **Backup frequency** | Daily          | Custom options |
| **Data export**      | Available      | Enhanced       |

<Info>
  Contact ButterCMS sales for specific enterprise retention policies and compliance requirements.
</Info>

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

| Requirement                | ButterCMS support                     |
| -------------------------- | ------------------------------------- |
| **Content audit trail**    | Full version history with attribution |
| **Approval documentation** | Workflow history preserved            |
| **Change tracking**        | Who, what, when for all changes       |
| **Data retention**         | Configurable 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 type       | Frequency  | Availability                       |
| ----------------- | ---------- | ---------------------------------- |
| **Content data**  | Daily      | Enterprise feature for restoration |
| **Media files**   | Continuous | CDN-backed storage                 |
| **Configuration** | On change  | Included 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

<CardGroup cols={2}>
  <Card title="Plan schema changes" icon="pen-ruler">
    Before modifying content models, consider the impact on historical versions
  </Card>

  <Card title="Preserve media" icon="images">
    Don't delete media files that may be referenced by historical content
  </Card>

  <Card title="Document changes" icon="file-lines">
    Keep external records of significant schema modifications
  </Card>

  <Card title="Export critical content" icon="download">
    Periodically export important content for your own records
  </Card>
</CardGroup>

### 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

<AccordionGroup>
  <Accordion title="How long are versions retained?">
    ButterCMS retains all version history indefinitely. There is no automatic deletion of historical versions based on time or count.
  </Accordion>

  <Accordion title="Can I delete old versions?">
    Individual versions cannot be deleted from the history. The complete version timeline is preserved for audit and recovery purposes.
  </Accordion>

  <Accordion title="What happens if I delete content entirely?">
    When content is deleted, its version history is removed. Consider unpublishing rather than deleting if you may need to restore later.
  </Accordion>

  <Accordion title="Are version histories backed up?">
    Yes, version histories are included in ButterCMS's backup systems. Enterprise customers can access enhanced backup and restoration options.
  </Accordion>

  <Accordion title="Can I export version history?">
    The standard API provides access to current content. For full version history export, contact ButterCMS support.
  </Accordion>

  <Accordion title="How do schema changes affect existing content?">
    Existing content data is preserved, but new fields won't have data in historical versions, and removed fields won't be visible.
  </Accordion>
</AccordionGroup>