payload-clienthub

Automatic monthly invoicing with PDF generation, Swiss QR Bill support, and multi-language email delivery for Payload CMS.

Overview

payload-clienthub adds a full invoicing workflow to Payload -- clients, services, and invoices are managed as collections. Recurring services are automatically detected when due, rendered as localized PDF invoices (with Swiss QR Bill support), and emailed to each client. A single endpoint processes all clients at once, so you can wire it up to a scheduler and forget about it.

Features

• Client & service management -- track clients, contacts, and one-time/monthly/yearly services.
• PDF invoices -- generated with itemized line items, company branding, and Swiss QR Bill payment slips for CH-based companies.
• Multi-language -- invoices and emails are localized in DE, FR, IT, and EN.
• Batch endpoint -- one endpoint processes all clients at once; authenticate with a shared secret to call it from any scheduler.

Installation

pnpm add payload-clienthub

Usage

// payload.config.ts
import { buildConfig } from 'payload';
import { clienthubPlugin } from 'payload-clienthub';

export default buildConfig({
  // ...
  plugins: [
    clienthubPlugin({
      cronSecret: process.env.CRON_SECRET!,
    }),
  ],
});

Trigger invoice generation for all clients by calling the batch endpoint (e.g. from a monthly scheduler):

curl -H "Authorization: Bearer $CRON_SECRET" \
  https://your-app.com/api/plugin-invoices/process-all-clients

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | cronSecret | string | — | Required. Shared secret used to authenticate batch requests via the Authorization: Bearer header. | | clientsCollectionSlug | CollectionSlug | 'clients' | Slug for the auto-created clients collection. | | servicesCollectionSlug | CollectionSlug | 'services' | Slug for the auto-created services collection. | | invoicesCollectionSlug | CollectionSlug | 'invoices' | Slug for the auto-created invoices collection. | | invoicePdfsCollectionSlug | CollectionSlug | 'invoice-pdfs' | Slug for the auto-created invoice PDFs upload collection. | | onError | (error: Error, context: { operation: string; metadata?: Record<string, unknown> }) => void | console.error | Custom error handler called when PDF generation or email delivery fails. |

Contributing

This plugin lives in the payload-plugins monorepo.

Development

pnpm install

# watch this plugin for changes
pnpm --filter payload-clienthub dev

# run the Payload dev app (in a second terminal)
pnpm --filter sandbox dev

The sandbox/ directory is a Next.js + Payload app that imports plugins via workspace:* — use it to test changes locally.

Code quality

• Formatting & linting — handled by Biome, enforced on commit via husky + lint-staged.
• Commits — must follow Conventional Commits with a valid scope (e.g. fix(payload-clienthub): ...).
• Changesets — please include a changeset in your PR by running pnpm release.

Issues & PRs

Bug reports and feature requests are welcome — open an issue.

License

MIT