Trash

Trash (also known as soft delete) allows documents to be marked as deleted without being permanently removed. When enabled on a collection, deleted documents will receive a deletedAt timestamp, making it possible to restore them later, view them in a dedicated Trash view, or permanently delete them.

Soft delete is a safer way to manage content lifecycle, giving editors a chance to review and recover documents that may have been deleted by mistake.

To enable soft deleting for a collection, set the trash property to true:

When enabled, Payload automatically injects a deletedAt field into the collection's schema. This timestamp is set when a document is soft-deleted, and cleared when the document is restored.

Once trash is enabled, the Admin Panel provides a dedicated Trash view for each collection:

• A new route is added at /collections/:collectionSlug/trash
• The Trash view shows all documents that have a deletedAt timestamp

From the Trash view, you can:

• Use bulk actions to manage trashed documents:
• Restore to clear the deletedAt timestamp and return documents to their original state
• Delete to permanently remove selected documents
• Empty Trash to select and permanently delete all trashed documents at once
• Enter each document's edit view, just like in the main list view. While in the edit view of a trashed document:
• All fields are in a read-only state
• Standard document actions (e.g., Save, Publish, Restore Version) are hidden and disabled.
• The available actions are Restore and Permanently Delete.
• Access to the API, Versions, and Preview views is preserved.

When deleting a document from the main collection List View, Payload will soft-delete the document by default. A checkbox in the delete confirmation modal allows users to skip the trash and permanently delete instead.

Soft deletes are fully supported across all Payload APIs: Local, REST, and GraphQL.

The following operations respect and support the trash functionality:

• find
• findByID
• update
• updateByID
• delete
• deleteByID
• findVersions
• findVersionByID

Passing trash: true to these operations will include soft-deleted documents in the query results.

To return only soft-deleted documents, you must combine trash: true with a where clause that checks if deletedAt exists.

Return all documents including trashed:

Return only trashed documents:

Return only non-trashed documents:

Return all documents including trashed:

Return only trashed documents:

Return only non-trashed documents:

Return all documents including trashed:

Return only trashed documents:

Return only non-trashed documents:

All trash-related actions (soft delete, permanent delete, restore) respect the delete access control defined in your collection config.

This means:

• If a user is denied delete access, they cannot soft delete or permanently delete documents

You can configure access control to allow some users to trash documents while restricting permanent deletion to admins only. This is useful when you want editors to be able to "delete" content (move to trash) but only allow administrators to permanently remove data.

The delete access control function receives a data argument that contains the document data being set during the operation:

• When trashing: data.deletedAt will be set to a timestamp
• When permanently deleting: data will be undefined

This pattern is similar to how publish access control works with data._status.

In the Admin Panel, when a user has permission to trash but not permanently delete:

• The delete button will be visible
• The "Delete permanently" checkbox in the confirmation modal will be hidden
• The user can only move documents to trash

When a document is soft-deleted:

• It can no longer have a version restored until it is first restored from trash
• Attempting to restore a version while the document is in trash will result in an error
• This ensures consistency between the current document state and its version history

However, versions are still fully visible and accessible from the edit view of a trashed document. You can view the full version history, but must restore the document itself before restoring any individual version.