feat(spec)!: document official plugin endpoints

[maximseshuk]

What

Documents the endpoints of the official Payload plugins (ecommerce, Stripe, MCP, SEO, search, multi-tenant, import-export, R2 storage) when the plugin is installed, and moves to Payload ^4.0.0-beta.0.

Breaking:

• Payload 4.0.0-beta.0 or later is required.
• An operation in extension paths now replaces the generated operation with the same path and method instead of deep-merging.
• OperationKind / OperationContext.kind can be 'plugin'.
• Official plugin endpoints appear in the spec. includeCustom: false does not hide them. excludeOperations: [{ kind: 'plugin' }] does.

Also:

• excludeOperations rules take plugin. A custom endpoint sets it with x-payload-plugin.
• Upload POST /{id}/rename and the version param on GET /file/{filename}.
• Plugin error translation keys are named errorPlugin<Scope><code> and errorStorage<Adapter><code> in all 44 locales.

Why

Official plugins add REST endpoints that the spec did not show. Users had to document them by hand. Payload 4 is now in beta, so the canary range is gone.

How I tested it

• Unit tests (179) cover each plugin, install detection, tag collisions, the plugin filter, extension path priority, unique payment operation ids and transform isolation.
• Integration tests (97) run on sqlite against the dev app.
• pnpm build and pnpm docs:validate pass.

Checklist

• pnpm typecheck && pnpm lint && pnpm format && pnpm test:unit pass
• Tests added or updated for the behavior change
• README.md and docs/ updated if users will notice the change
• Commit subjects follow Conventional Commits (fix: ..., feat: ...)

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
payload-plugin-openapi	🟢 Ready	View Preview	Oct 10, 2026, 7:09 PM

💡 Tip: Enable Automations to automatically generate PRs for you.