Drafts

Payload's Draft functionality builds on top of the Versions functionality to allow you to make changes to your collection documents and globals, but publish only when you're ready. This functionality allows you to build powerful Preview environments for your data, where you can make sure your changes look good before publishing documents.

By enabling Versions with Drafts, your collections and globals can maintain newer, and unpublished versions of your documents. It's perfect for cases where you might want to work on a document, update it and save your progress, but not necessarily make it publicly published right away. Drafts are extremely helpful when building preview implementations.

If Drafts are enabled, the typical Save button is replaced with new actions which allow you to either save a draft, or publish your changes.

Options

Collections and Globals both support the same options for configuring drafts. You can either set versions.drafts to true, or pass an object to configure draft properties.

Draft Option	Description
`autosave`	Enable `autosave` to automatically save progress while documents are edited. To enable, set to `true` or pass an object with options.
`localizeStatus`	Beta. Localizes the `_status` field when using Localization. Default is `false`.
`schedulePublish`	Allow for editors to schedule publish / unpublish events in the future. More
`validate`	Set `validate` to `true` to validate draft documents when saved. Default is `false`.

Database changes

By enabling drafts on a collection or a global, Payload will automatically inject a new field into your schema called _status. The _status field is used internally by Payload to store if a document is set to draft or published.

Admin UI status indication

Within the Admin UI, if drafts are enabled, a document can be shown with one of three "statuses":

Draft - if a document has never been published, and only draft versions of the document are present
Published - if a document is published and there are no newer drafts available
Changed - if a document has been published, but there are newer drafts available and not yet published

Draft API

Using the `draft` parameter

When drafts are enabled, the create, update, find, and findByID operations for REST, GraphQL, and Local APIs expose a draft parameter. For write operations, it controls validation and where data is written. For read operations, it determines whether to return draft versions.

1// REST API
2POST /api/your-collection?draft=true
3
4// Local API
5await payload.create({
6  collection: 'your-collection',
7  data: {
8    // your data here
9  },
10  draft: true,
11})
12
13// GraphQL
14mutation {
15  createYourCollection(data: { ... }, draft: true) {
16    // ...
17  }
18}

Understanding draft parameter and _status field

The draft parameter and _status field work together but serve different purposes:

draft parameter - Controls two things:

Validation: When draft: true, required fields are not enforced, allowing you to save incomplete documents
Write location: Determines whether the main collection document is updated

draft: true - Saves ONLY to versions table (main collection unchanged)
draft: false or omitted - Saves to BOTH main collection AND versions table

_status field - Indicates whether a document is published or in draft state

Defaults to 'draft' when not explicitly provided
Can be explicitly set in your data to 'published' or 'draft'

First document creation

When you first create a document, it's always written to the main collection (since no document exists yet):

If you don't specify _status, it defaults to _status: 'draft'
A version is also created in the versions table
The draft parameter controls validation but doesn't change where the initial document is written

Subsequent updates

After initial creation, the draft parameter controls where your updates are written:

draft: true - Only the versions table is updated; the main collection document remains unchanged
draft: false or omitted - Both the main collection and versions table are updated

Important: The draft parameter does NOT control whether a document is published or not. A document remains with _status: 'draft' by default unless you explicitly set _status: 'published' in your data.

Publishing a document

To publish a document, you must explicitly set _status: 'published' in your data. When you do this:

If you use draft: false or omit it, the main collection will be updated with the published status
If you use draft: true, the _status: 'published' takes precedence and will still update the main collection as published (overriding the draft: true behavior)

Quick reference

Operation	`draft` param	`_status` in data	Result
Create	`true` or `false`	omitted	Main collection updated with `_status: 'draft'`
Create	`true` or `false`	`'published'`	Main collection updated with `_status: 'published'`
Update	`true`	omitted or `'draft'`	Only versions table updated, main collection unchanged
Update	`true`	`'published'`	Main collection updated with `_status: 'published'` (override)
Update	`false` or omitted	omitted	Main collection updated with `_status: 'draft'`
Update	`false` or omitted	`'published'`	Main collection updated with `_status: 'published'`

Required fields

Setting _status: "draft" will not bypass required field validation. You need to set draft: true to save incomplete documents as shown in the previous examples.

Reading drafts vs. published documents

In addition to the draft argument within create and update operations, a draft argument is also exposed for find and findByID operations.

When draft is set to true while reading a document, Payload will return the most recent version from the versions table, regardless of whether it's a draft or published document.

Example scenario:

You create a document with _status: 'published' (published in main collection)
You update with draft: true to make changes without affecting the published version
You update again with draft: true to make more draft changes

At this point, your published document remains unchanged in the main collection, and you have two newer draft versions in the _[collectionSlug]_versions table.

When you fetch the document with a standard find or findByID operation, the published document from the main collection is returned and draft versions are ignored.

However, if you pass draft: true to the read operation, Payload will return the most recent version from the versions table. In the scenario above with two draft versions, you'll get the latest (second) draft.

Note: If there are no newer drafts (e.g., you published a document and haven't made draft changes since), querying with draft: true will still return the latest version from the versions table, which would be the same published content as in the main collection.

Controlling who can see Collection drafts

Restricting draft access

You can use the read Access Control method to restrict who is able to view drafts of your documents by simply returning a query constraint which restricts the documents that any given user is able to retrieve.

Here is an example that utilizes the _status field to require a user to be logged in to retrieve drafts:

1import type { CollectionConfig } from 'payload'
2
3export const Pages: CollectionConfig = {
slug: 'pages',
access: {
  read: ({ req }) => {
    // If there is a user logged in,
    // let them retrieve all documents
    if (req.user) return true
10
    // If there is no user,
    // restrict the documents that are returned
    // to only those where `_status` is equal to `published`
    return {
      _status: {
        equals: 'published',
      },
    }
  },
},
versions: {
  drafts: true,
},
//.. the rest of the Pages config here
25}

Note regarding adding versions to an existing collection

If you already have a collection with documents, and you opt in to draft functionality after you have already created existing documents, all of your old documents _will not have a _status field_ until you resave them. For this reason, if you are _adding_ versions into an existing collection, you might want to write your Access Control function to allow for users to read both documents where _status is equal to "published" as well as where _status does not exist.

Here is an example for how to write an Access Control function that grants access to both documents where _status is equal to "published" and where _status does not exist:

1import type { CollectionConfig } from 'payload'
2
3export const Pages: CollectionConfig = {
slug: 'pages',
access: {
  read: ({ req }) => {
    // If there is a user logged in,
    // let them retrieve all documents
    if (req.user) return true
10
    // If there is no user,
    // restrict the documents that are returned
    // to only those where `_status` is equal to `published`
    // or where `_status` does not exist
    return {
      or: [
        {
          _status: {
            equals: 'published',
          },
        },
        {
          _status: {
            exists: false,
          },
        },
      ],
    }
  },
},
versions: {
  drafts: true,
},
//.. the rest of the Pages config here
35}

Controlling who can publish

You can use update Access Control to restrict who can publish documents by returning a query constraint on the _status field. When this constraint prevents publishing, the Admin UI automatically hides the Publish and Unpublish buttons.

Here is an example where admins can publish, but editors can only save drafts:

1import type { CollectionConfig } from 'payload'
2
3export const Posts: CollectionConfig = {
slug: 'posts',
access: {
  update: ({ req: { user } }) => {
    if (!user) {
      // If there is no user, they can't update anything
      return false
    }
11
    // Admins can update any document, including publishing
    if (user?.role === 'admin') return true
14
    // Editors can only update documents that are not published.
    return {
      _status: {
        equals: 'draft',
      },
    }
  },
},
versions: {
  drafts: true,
},
26}

The update function returns a query constraint instead of a boolean. Payload appends this constraint to the update query, so only documents where _status is not published can be updated by editors. This also blocks scheduled publish jobs from executing for those users.

The create function uses a data check instead since there is no existing document to query against.

Scheduled publish

Payload provides for an ability to schedule publishing / unpublishing events in the future, which can be helpful if you need to set certain documents to "go live" at a given date in the future, or, vice versa, revert to a draft state after a certain time has passed.

You can enable this functionality on both collections and globals via the versions.drafts.schedulePublish: true property.

Unpublishing drafts

If a document is published, the Payload Admin UI will be updated to show an "unpublish" button at the top of the sidebar, which will "unpublish" the currently published document. Consider this as a way to "revert" a document back to a draft state. On the API side, this is done by simply setting _status: 'draft' on any document.

Reverting to published

If a document is published, and you have made further changes which are saved as a draft, Payload will show a "revert to published" button at the top of the sidebar which will allow you to reject your draft changes and "revert" back to the published state of the document. Your drafts will still be saved, but a new version will be created that will reflect the last published state of the document.

Was this page helpful?

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

Drafts

Options

Database changes

Draft API

Using the `draft` parameter

Reading drafts vs. published documents

Controlling who can see Collection drafts

Restricting draft access

Controlling who can publish

Scheduled publish

Unpublishing drafts

Reverting to published

Autosave

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

Drafts

Options

Database changes

Draft API

Using the draft parameter

Reading drafts vs. published documents

Controlling who can see Collection drafts

Restricting draft access

Controlling who can publish

Scheduled publish

Unpublishing drafts

Reverting to published

Autosave

Using the `draft` parameter