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

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.