API

Subscription Payments

Owner endpoints for viewing subscription payment history and individual payment records.

Base path: /api/v1/subscription

Used by: owner-booki-web-app · Role: owner, branch-manager
organizationId: From JWT token

These endpoints allow owners and branch managers to view their organization's subscription payment history.

GET `/api/v1/subscription/my-payments` — List My Subscription Payments

Auth: Protected (Authorization: Bearer <accessToken>)
Used by: owner-booki-web-app · Role: owner, branch-manager
Description: Retrieve the full subscription payment history for the authenticated user's organization.

Request

Query Parameters (optional):

page (number, default: 1): Page number
limit (number, default: 10, max: 100): Results per page
status (string): Filter by payment status — pending | paid | failed | refunded
sort (string, default: _id): Sort field
order (string, default: desc): asc | desc

GET /api/v1/subscription/my-payments?page=1&status=paid

Response (200 OK)

{
  "items": [
    {
      "_id": "507f191e810c19729de860fa",
      "organizationId": "507f191e810c19729de860ea",
      "amount": 999,
      "status": "paid",
      "interval": "monthly",
      "paidAt": "2026-04-01T10:00:00Z",
      "createdAt": "2026-04-01T09:55:00Z"
    },
    {
      "_id": "507f191e810c19729de861fb",
      "organizationId": "507f191e810c19729de860ea",
      "amount": 999,
      "status": "paid",
      "interval": "monthly",
      "paidAt": "2026-03-01T10:00:00Z",
      "createdAt": "2026-03-01T09:55:00Z"
    }
  ],
  "pages": 1,
  "pageRange": "1-2 of 2"
}

Error Responses

401 Unauthorized — No valid token:

{
  "statusCode": 401,
  "message": "Access token is required to proceed."
}

cURL Example

curl -X GET "http://localhost:4001/api/v1/subscription/my-payments?page=1" \
  -H "Authorization: Bearer OWNER_TOKEN"

GET `/api/v1/subscription/payments/:id` — Get Subscription Payment by ID

Auth: Protected (Authorization: Bearer <accessToken>)
Used by: owner-booki-web-app · Role: owner, branch-manager
Description: Retrieve a single subscription payment record by its ID.

Request

GET /api/v1/subscription/payments/507f191e810c19729de860fa

Path Parameters:

id (string, required): Payment record ID (24-hex)

Response (200 OK)

{
  "_id": "507f191e810c19729de860fa",
  "organizationId": "507f191e810c19729de860ea",
  "userId": "507f1f77bcf86cd799439011",
  "amount": 999,
  "status": "paid",
  "interval": "monthly",
  "paymentMethod": "maya",
  "referenceNumber": "REF-2026-0001",
  "paidAt": "2026-04-01T10:00:00Z",
  "createdAt": "2026-04-01T09:55:00Z"
}

Error Responses

404 Not Found — Payment not found:

{
  "statusCode": 404,
  "message": "Subscription payment not found."
}

cURL Example

curl -X GET "http://localhost:4001/api/v1/subscription/payments/507f191e810c19729de860fa" \
  -H "Authorization: Bearer OWNER_TOKEN"

Packages - Public

Public tenant-scoped package endpoints for customers browsing available services.

Users - Saved Payment Methods

Customer endpoints for managing saved Stripe payment methods.