Payload CMS is a TypeScript-first headless CMS that supports MongoDB and PostgreSQL. Its default identifier is MongoDB ObjectId — but Payload supports fully custom id fields. Switching to UUID v7 gives globally portable IDs, millisecond-precision time ordering, and compatibility with any database backend. See UUID in MongoDB for the MongoDB storage context.
Setup
npm install uuid
npm install payload @payloadcms/db-mongodb
# or for PostgreSQL: npm install @payloadcms/db-postgres
Collection config with UUID v7 id
// collections/Orders.ts
import type { CollectionConfig } from 'payload';
import { v7 as uuidv7 } from 'uuid';
import { validate } from 'uuid';
export const Orders: CollectionConfig = {
slug: 'orders',
fields: [
{
name: 'id',
type: 'text',
required: true,
admin: { readOnly: true },
validate: (val) => {
if (!validate(val as string)) return 'Must be a valid UUID';
return true;
},
},
{
name: 'customerId',
type: 'text',
required: true,
},
{
name: 'total',
type: 'number',
required: true,
},
{
name: 'status',
type: 'select',
defaultValue: 'pending',
options: ['pending', 'processing', 'shipped', 'delivered'],
},
],
hooks: {
beforeOperation: [
({ args, operation }) => {
if (operation === 'create' && args.data) {
// Generate UUID v7 before creation
args.data.id = uuidv7();
}
return args;
},
],
},
};
Payload config
// payload.config.ts
import { buildConfig } from 'payload';
import { mongooseAdapter } from '@payloadcms/db-mongodb';
import { Orders } from './collections/Orders';
export default buildConfig({
collections: [Orders],
db: mongooseAdapter({
url: process.env.MONGODB_URI!,
}),
secret: process.env.PAYLOAD_SECRET!,
});
PostgreSQL adapter variant
import { postgresAdapter } from '@payloadcms/db-postgres';
export default buildConfig({
collections: [Orders],
db: postgresAdapter({
pool: { connectionString: process.env.DATABASE_URL! },
}),
secret: process.env.PAYLOAD_SECRET!,
});
With PostgreSQL, UUID v7 TEXT primary keys sort lexicographically = chronologically. See PostgreSQL 18 Native UUID v7.
REST API usage
Payload generates REST endpoints automatically:
// Create order via Payload REST API
const response = await fetch('/api/orders', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
customerId: 'user-uuid-here',
total: 49.99,
}),
});
const { doc } = await response.json();
console.log(doc.id); // UUID v7 — e.g. '018fbe3a-4c5d-7b12-8f3e-1a2b3c4d5e6f'
// Find by UUID v7 id
const found = await fetch(`/api/orders/${doc.id}`);
// Paginate chronologically (UUID v7 sort)
const page = await fetch('/api/orders?sort=id&limit=20');
GraphQL API usage
# Payload auto-generates this from the collection config
query GetOrder($id: String!) {
Order(id: $id) {
id
customerId
total
status
}
}
query ListOrders($limit: Int) {
Orders(sort: "id", limit: $limit) {
docs {
id
customerId
total
status
}
totalDocs
nextPage
}
}
Local API usage (server-side)
import { getPayloadHMR } from '@payloadcms/next/utilities';
import config from '@payload-config';
const payload = await getPayloadHMR({ config });
// Create — UUID v7 generated by beforeOperation hook
const order = await payload.create({
collection: 'orders',
data: { customerId: 'user-id', total: 99.99 },
});
console.log(order.id); // UUID v7
// Find by UUID v7 id
const found = await payload.findByID({
collection: 'orders',
id: order.id,
});
// Cursor pagination with UUID v7
const page = await payload.find({
collection: 'orders',
sort: 'id', // UUID v7 lexicographic = chronological
limit: 20,
where: {
id: { greater_than: cursor },
},
});
See UUID v7 for Cursor Pagination.
Further reading
- UUID in MongoDB — Replacing ObjectId with UUID v7
- PostgreSQL 18 Native UUID v7
- UUID in Databases — Storage and Indexing
- UUID v7 for Cursor Pagination
- UUID v7 in Mongoose — MongoDB ODM
External references
Frequently asked questions
How do I use UUID v7 as the id field in a Payload CMS collection?
Define a custom id field of type text in your collection config and use a beforeOperation hook to generate the UUID v7 value before creation: args.data.id = uuidv7(). Payload reads the id field and uses it as the document identifier in both MongoDB and PostgreSQL adapters. Set required: true and add a validate function to enforce UUID format.
Does UUID v7 work with Payload CMS's PostgreSQL adapter?
Yes. The Payload PostgreSQL adapter uses Drizzle ORM under the hood. Define the collection with a custom text id field and Drizzle will create a TEXT PRIMARY KEY column. UUID v7 strings sort lexicographically in PostgreSQL's ORDER BY, giving chronological ordering. Alternatively, use PostgreSQL's native UUID type by configuring the field with a custom Drizzle column type.
How does Payload CMS expose UUID v7 IDs in its REST and GraphQL APIs?
Payload automatically exposes the id field in REST responses (GET /api/orders/:id) and GraphQL queries. With UUID v7, the id is a string that clients use for lookups and pagination. The Payload REST API supports cursor-based pagination via the pagination query parameter — combine with sort=id for chronological UUID v7 ordering.