Manage the complete subscription lifecycle, automated free trials, plan tiers, and client enrollment.

Subscriptions & Free Trials

SubsManager models recurring subscriptions as deterministic finite-state machines. It supports instantaneous free trials, offline EFT bank payment pending states, online gateway card checkouts, and dunning transitions.

1. Subscription State Machine

Loading diagram...

State Definitions & Access Rules

Status	Definition	Entitlement Access
`trialing`	Subscriber is within an active free trial window.	✅ Full Access
`active`	Payment received and verified; valid until `endDate`.	✅ Full Access
`pending`	Subscription initiated; awaiting offline EFT deposit or card checkout.	⏳ Policy Dependent
`past_due`	Term expired without confirmed payment; dunning cycle in progress.	⚠️ Restricted / Grace Period
`cancelled`	Terminated by user or tenant administrator.	❌ No Access
`expired`	Free trial or grace period elapsed without payment reconciliation.	❌ No Access
`paused`	Administrative pause applied to the subscription.	❌ No Access

2. Plan Catalog & Free Trials

Retrieve your application's configured plans to display pricing tables on your website or in your application:

Endpoint: GET /plans
Headers: Authorization: Bearer ap_...

Response (200 OK):

{
  "plans": [
    {
      "_id": "67da8102f4b...",
      "name": "Professional Plan",
      "description": "Full access to advanced features",
      "price": 299.00,
      "currency": "ZAR",
      "billingCycle": "monthly",
      "trialPeriodDays": 14,
      "features": [
        "Unlimited API access",
        "24/7 Priority Support",
        "Custom domain"
      ],
      "isActive": true
    },
    {
      "_id": "67da8103a1c...",
      "name": "Starter Plan",
      "description": "Essential features for small teams",
      "price": 99.00,
      "currency": "ZAR",
      "billingCycle": "monthly",
      "trialPeriodDays": 0,
      "features": ["Up to 5 team members"],
      "isActive": true
    }
  ]
}

Automatic Trial Detection

When trialPeriodDays > 0, SubsManager begins a free trial upon signup without prompting for credit card details.

3. Client Registration

Endpoint: POST /clients
Body:

{
  "externalId": "usr_99182",
  "email": "sarah.connor@example.com",
  "name": "Sarah Connor",
  "metadata": {
    "organization": "Cyberdyne Systems"
  }
}

4. Creating Subscriptions

Initiate a subscription by supplying the client's externalId and the desired planId:

Endpoint: POST /subscriptions
Body:

{
  "externalId": "usr_99182",
  "planId": "67da8102f4b...",
  "startDate": "2026-10-01T00:00:00.000Z",
  "successUrl": "https://myapp.com/billing?status=success",
  "cancelUrl": "https://myapp.com/billing?status=cancelled"
}

Execution Pathways:

Path A: Free Trial Plan (`trialPeriodDays > 0`)

The subscription is placed into status trialing. No upfront payment is required:

{
  "subscription": {
    "_id": "67da9120...",
    "referenceNumber": "SUB-J92K4M",
    "status": "trialing",
    "startDate": "2026-10-01T00:00:00.000Z",
    "trialStart": "2026-10-01T00:00:00.000Z",
    "trialEnd": "2026-10-15T00:00:00.000Z",
    "autoRenew": true
  }
}

Path B: Offline EFT Plan (No Gateway Configured)

The subscription starts in status pending. An official invoice with banking details and payment reference is generated immediately, and an email is dispatched to the subscriber:

{
  "subscription": {
    "_id": "67da9120...",
    "referenceNumber": "SUB-J92K4M",
    "status": "pending",
    "startDate": "2026-10-01T00:00:00.000Z"
  }
}

Path C: Online Gateway Plan (Yoco / Paystack / Stripe Enabled)

The response contains a checkoutUrl where you must redirect the user to complete payment:

{
  "subscription": {
    "_id": "67da9120...",
    "referenceNumber": "SUB-J92K4M",
    "status": "pending"
  },
  "checkoutUrl": "https://payments.yoco.com/checkout/ch_91283..."
}

5. Checking Active Subscriber Entitlements

To quickly evaluate whether a customer is entitled to access your platform:

Endpoint: GET /subscriptions/current?externalId=usr_99182

Response (200 OK):

{
  "subscription": {
    "_id": "67da9120...",
    "referenceNumber": "SUB-J92K4M",
    "status": "active",
    "planId": {
      "_id": "67da8102f4b...",
      "name": "Professional Plan",
      "price": 299.00,
      "currency": "ZAR",
      "billingCycle": "monthly"
    },
    "startDate": "2026-10-01T00:00:00.000Z",
    "endDate": "2026-11-01T00:00:00.000Z"
  }
}

6. Direct Activation & Cancellation

Manual EFT Activation

When your finance team verifies payment:

POST /api/v1/subscriptions/67da9120.../activate
Authorization: Bearer ap_...

Subscription Cancellation

Transitions status to cancelled:

POST /api/v1/subscriptions/67da9120...
Authorization: Bearer ap_...

Subscriptions & Free Trials

On this page