Payload is joining Figma!Read the announcement
Simplify your stack and build anything. Or everything.
Schedule a Demo
USE CASES
Headless CMSEnterprise App BuilderHeadless E-CommerceDigital Asset Management
FEATURES
Multi-TenancyWhite LabelLocalizationAccess ControlAuth
CASE STUDIES

See what others are building with Payload.

Browse Case Studies
Build tomorrow’s web with a modern solution you truly own.
PAYLOAD IS FOR
DevelopersMarketing teamsEnterprise companiesAgencies & Consultancies
COMPARE PAYLOAD
Payload vs WordPressPayload vs ContentfulPayload vs SanityPayload vs StrapiPayload vs Directus
AGENCY TESTIMONIAL

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

Become a PartnerFind a Partner
Code-based nature means you can build on top of it to power anything.
Resources
DocumentationExamplesTemplatesGitHubReleasesBlogGuides & Tutorials
Community
RoadmapDiscordCommunity Help
Resources for Developers

Get the resources you need to start building today

Guides & TutorialsExplore Docs
It’s time to take back your content infrastructure.
Schedule a Demo
Enterprise Features
SSOAI Auto-EmbeddingPublishing WorkflowsVisual EditorStatic A/B testingAI features
Customer Stories
MicrosoftASICSBlue OriginHello BelloTekton
Featured Customer Story

Microsoft chose Payload to tell the world about AI.

Read the case studyBrowse all
LoginGet Started

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.

Collection Configuration

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

1
import type { CollectionConfig } from 'payload'
2
3
export const Posts: CollectionConfig = {
4
slug: 'posts',
5
trash: true,
6
fields: [
7
{
8
name: 'title',
9
type: 'text',
10
},
11
// other fields...
12
],
13
}

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.

Admin Panel behavior

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.

API Support

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

Understanding trash Behavior

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.

Examples

Local API

Return all documents including trashed:

1
const result = await payload.find({
2
collection: 'posts',
3
trash: true,
4
})

Return only trashed documents:

1
const result = await payload.find({
2
collection: 'posts',
3
trash: true,
4
where: {
5
deletedAt: {
6
exists: true,
7
},
8
},
9
})

Return only non-trashed documents:

1
const result = await payload.find({
2
collection: 'posts',
3
trash: false,
4
})

REST

Return all documents including trashed:

1
GET /api/posts?trash=true

Return only trashed documents:

1
GET /api/posts?trash=true&where[deletedAt][exists]=true

Return only non-trashed documents:

1
GET /api/posts?trash=false

GraphQL

Return all documents including trashed:

1
query {
2
Posts(trash: true) {
3
docs {
4
id
5
deletedAt
6
}
7
}
8
}

Return only trashed documents:

1
query {
2
Posts(
3
trash: true
4
where: { deletedAt: { exists: true } }
5
) {
6
docs {
7
id
8
deletedAt
9
}
10
}
11
}

Return only non-trashed documents:

1
query {
2
Posts(trash: false) {
3
docs {
4
id
5
deletedAt
6
}
7
}
8
}

Access Control

All trash-related actions (delete, permanent delete) 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

Versions and 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.

Next

TypeScript - Overview