API

Admin - Billing & Subscriptions

Admin endpoints for billing management, subscriptions, invoices, and revenue tracking.

Base path: /api/v1/admin/billing

Used by: admin-booki-web-app · Role: admin
organizationId: Not applicable (admin sees all)

Admin billing endpoints provide access to revenue tracking, subscription management, invoicing, and financial reporting for organizations.

Note: The routes below reflect the actual implemented API routes. Endpoints listed here have been verified against booki-api/src/routes/.

GET `/api/v1/admin/billing/stats` — Platform Billing Stats

Auth: Protected (Authorization: Bearer <accessToken>) · admin
Used by: admin-booki-web-app · Role: admin
Description: Fetch overall platform billing statistics and financial overview.

Request

GET /api/v1/admin/billing/stats

Response (200 OK)

{
  "stats": {
    "totalMRR": 23975,
    "totalARR": 287700,
    "activeSubscriptions": 125,
    "totalRevenue": 1250000,
    "paymentMethods": {
      "maya": 780000,
      "cash": 470000
    }
  }
}

cURL Example

curl -X GET http://localhost:4001/api/v1/admin/billing/stats \
  -H "Authorization: Bearer ADMIN_TOKEN"

GET `/api/v1/admin/billing/subscriptions` — List Subscriptions

Auth: Protected (Authorization: Bearer <accessToken>) · admin
Used by: admin-booki-web-app · Role: admin
Description: Fetch all active and past subscriptions across the platform.

Request

Query Parameters (optional):

page (number, default: 1)
limit (number, default: 10, max: 100)
search (string): Search term
status (string): trial | active | suspended | cancelled
interval (string): monthly | annually
sort (string, default: _id)
order (string, default: desc): asc | desc

GET /api/v1/admin/billing/subscriptions?page=1&status=active

Response (200 OK)

{
  "items": [
    {
      "_id": "607f1f77bcf86cd799431234",
      "organizationId": "507f191e810c19729de860ea",
      "organizationName": "Booki Salon",
      "status": "active",
      "interval": "monthly",
      "startDate": "2026-01-01T00:00:00Z",
      "nextBillingDate": "2026-04-01T00:00:00Z"
    }
  ],
  "pages": 1,
  "pageRange": "1-1 of 1"
}

cURL Example

curl -X GET "http://localhost:4001/api/v1/admin/billing/subscriptions?status=active" \
  -H "Authorization: Bearer ADMIN_TOKEN"

GET `/api/v1/admin/billing/subscriptions/:userId` — Get Subscription Details

Auth: Protected (Authorization: Bearer <accessToken>) · admin
Used by: admin-booki-web-app · Role: admin
Description: Fetch subscription details and payment history for a specific user/organization owner.

Request

GET /api/v1/admin/billing/subscriptions/507f1f77bcf86cd799439011

Path Parameters:

userId (string, required): Owner's user ID

Response (200 OK)

{
  "subscription": {
    "_id": "607f1f77bcf86cd799431234",
    "userId": "507f1f77bcf86cd799439011",
    "organizationName": "Booki Salon",
    "plan": "premium",
    "status": "active",
    "startDate": "2026-01-01T00:00:00Z",
    "nextBillingDate": "2026-05-01T00:00:00Z"
  }
}

cURL Example

curl -X GET http://localhost:4001/api/v1/admin/billing/subscriptions/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer ADMIN_TOKEN"

GET `/api/v1/admin/billing/subscriptions/:userId/pdf` — Download Subscription PDF

Auth: Protected (Authorization: Bearer <accessToken>) · admin
Used by: admin-booki-web-app · Role: admin
Description: Download subscription statement of account as PDF.

Request

GET /api/v1/admin/billing/subscriptions/507f1f77bcf86cd799439011/pdf

Response (200 OK)

Returns PDF file as binary data with attachment header.

cURL Example

curl -X GET http://localhost:4001/api/v1/admin/billing/subscriptions/507f1f77bcf86cd799439011/pdf \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  --output subscription-soa.pdf

POST `/api/v1/admin/billing/subscriptions/:userId/send-soa` — Send Statement of Account

Auth: Protected (Authorization: Bearer <accessToken>) · admin
Used by: admin-booki-web-app · Role: admin
Description: Email the statement of account PDF to the organization owner.

Request

POST /api/v1/admin/billing/subscriptions/507f1f77bcf86cd799439011/send-soa

Response (200 OK)

{
  "message": "Statement of account sent successfully",
  "sentTo": "owner@bookisalon.com"
}

cURL Example

curl -X POST http://localhost:4001/api/v1/admin/billing/subscriptions/507f1f77bcf86cd799439011/send-soa \
  -H "Authorization: Bearer ADMIN_TOKEN"

POST `/api/v1/admin/billing/trigger-soa-blast` — Trigger SOA Blast

Auth: Protected (Authorization: Bearer <accessToken>) · admin
Used by: admin-booki-web-app · Role: admin
Description: Trigger a bulk statement of account email send to all organization owners.

Request

POST /api/v1/admin/billing/trigger-soa-blast

Response (200 OK)

{
  "message": "SOA blast triggered successfully",
  "recipientCount": 125
}

cURL Example

curl -X POST http://localhost:4001/api/v1/admin/billing/trigger-soa-blast \
  -H "Authorization: Bearer ADMIN_TOKEN"

GET `/api/v1/admin/billing/invoices` — List Invoices

Auth: Protected (Authorization: Bearer <accessToken>) · admin
Used by: admin-booki-web-app · Role: admin
Description: Fetch all invoices/payments across the platform with filtering options.

Request

Query Parameters (optional):

page (number, default: 1)
limit (number, default: 10, max: 100)
search (string): Search term
status (string): pending | paid | failed | refunded
sort (string, default: _id)
order (string, default: desc): asc | desc

GET /api/v1/admin/billing/invoices?page=1&status=paid

Response (200 OK)

{
  "items": [
    {
      "_id": "507f191e810c19729de860ea",
      "organizationId": "507f191e810c19729de860ea",
      "amount": 1999,
      "status": "paid",
      "paidAt": "2026-03-10T14:30:00Z"
    }
  ],
  "pages": 1,
  "pageRange": "1-1 of 1"
}

cURL Example

curl -X GET "http://localhost:4001/api/v1/admin/billing/invoices?status=paid" \
  -H "Authorization: Bearer ADMIN_TOKEN"

GET `/api/v1/admin/billing/invoices/:paymentId` — Get Invoice by Payment ID

Auth: Protected (Authorization: Bearer <accessToken>) · admin
Used by: admin-booki-web-app · Role: admin
Description: Fetch a specific invoice/payment record by its payment ID.

Request

GET /api/v1/admin/billing/invoices/507f191e810c19729de860ea

Path Parameters:

paymentId (string, required): Payment ID

Response (200 OK)

Returns invoice/payment object (same structure as list item).

cURL Example

curl -X GET http://localhost:4001/api/v1/admin/billing/invoices/507f191e810c19729de860ea \
  -H "Authorization: Bearer ADMIN_TOKEN"

Billing Plans

Plans are dynamic and admin-configurable via the billing settings. Two plan identifiers are used in code:

Plan	Description
`free`	Default — no active subscription payment recorded
`pro`	Active — at least one successful subscription payment exists

Pricing (base price per branch) and trial period are set by the admin in billing settings, not hardcoded.

Invoice Status Reference

pending: Awaiting payment
paid: Payment received and confirmed
failed: Payment attempt failed
refunded: Payment refunded

Notes

All billing endpoints require admin role.
Invoices are generated from SubscriptionPayment records created via the Maya webhook.
All amounts in Philippine Pesos (PHP).

Owner - Customer Management

Owner endpoints for viewing customer profiles, booking history, and managing relationships.

Admin - Organizations Management

Admin endpoints for managing organizations, viewing stats, and organization-level operations.