API Reference

All API routes live under /api/. Protected routes require a valid Auth.js session. Cron routes require the x-cron-secret header (value from app setting security.cronSecret or env CRON_SECRET).

Authentication

GET/POST /api/auth/[...nextauth]

Auth.js catch-all. Handles sign-in, sign-out, session, and OAuth callbacks.

Providers: Credentials (email/password), Google OAuth.

Groups

GET /api/groups

List groups the authenticated user belongs to (admin or member).

Response: { "groups": [ { "_id", "name", "service", "role", "memberCount", "billing", "nextBillingDate", "unpaidCount" } ] }

POST /api/groups

Create a group. Body: name, service, billing, payment, members. Authenticated user becomes admin.

GET /api/groups/[groupId]

Get group details. Admin sees full config; members see limited info.

PATCH /api/groups/[groupId]

Update group. Admin only.

DELETE /api/groups/[groupId]

Soft-deactivate group. Admin only.

Members

POST /api/groups/[groupId]/members

Add member. Body: email, nickname, customAmount (optional). Admin only.

PATCH /api/groups/[groupId]/members/[memberId]

Update member. Admin only.

DELETE /api/groups/[groupId]/members/[memberId]

Remove member (soft). Admin only.

Billing

GET /api/groups/[groupId]/billing

List billing periods. Query: page, limit, status.

POST /api/groups/[groupId]/billing

Create billing period (e.g. variable mode). Admin only. Body: periodLabel, totalPrice, periodStart, periodEnd.

PATCH /api/groups/[groupId]/billing/[periodId]

Update period (e.g. waive member, add notes). Admin only.

Payment confirmation

GET /api/confirm/[token]

Handles “I’ve paid” email link. Token is HMAC-signed. No auth. Validates token, sets payment to member_confirmed, notifies admin, redirects to a thank-you URL.

POST /api/groups/[groupId]/billing/[periodId]/confirm

Admin confirms a member’s payment. Body: memberId, action (confirm | reject), notes (optional).

Notifications

POST /api/groups/[groupId]/notify

Trigger notifications manually. Body: type, message, channels. Admin only.

Cron

All cron routes require header: x-cron-secret: <secret>.

POST /api/cron/billing

Create billing periods for due groups.

POST /api/cron/reminders

Enqueue payment reminder tasks and run the notification worker. Response: enqueued, worker (claimed, completed, failed).

POST /api/cron/follow-ups

Reconcile overdue payments and enqueue admin nudge tasks, then run the worker. Response: overdueReconciled, adminNudgesEnqueued, worker.

POST /api/cron/notification-tasks

Run the notification task worker (claim and execute due tasks). Call frequently (e.g. every 5 min). Response: claimed, completed, failed, counts (pending, locked, completed, failed).

Error format

All errors use:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Human-readable message",
    "details": {}
  }
}

Common codes: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, CONFLICT, INTERNAL_ERROR.

Success format

Successful responses use:

{
  "data": { ... }
}

For the full request/response schemas and more endpoints, see docs/api-design.md in the repository.