payload-clienthub

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