Subscriptions API Overview

The Informer Subscriptions API provides endpoints for managing AI seat subscriptions. Subscriptions are managed through the License Manager and handle payment processing, billing cycles, and seat allocation. All routes are prefixed with /api.

Features

• Create Subscriptions - Purchase AI seat subscriptions with payment processing
• Manage Subscriptions - Update billing details and cancel subscriptions
• View Subscriptions - List all subscriptions with seat details
• Team Assignment - Associate subscriptions with teams

Authentication

All Subscription API endpoints require superuser permissions. Only administrators can manage subscriptions.

Billing Integration

Subscriptions integrate with:

• License Manager - Subscription lifecycle and seat management
• QuickBooks - Payment processing and billing
• Tax Calculation - Automatic tax estimation for purchases

Endpoints

GET /api/subscriptions

Get all subscriptions for the current license.

Authentication: Required (superuser)

Pre-blocks: Permission check for admin access

Response:

{
  "subscriptions": [
    {
      "id": "sub-123",
      "status": "active",
      "billingCycle": "monthly",
      "amount": 500.00,
      "taxes": 45.00,
      "cardLast4": "4242",
      "nextBillingDate": "2024-02-15T00:00:00Z",
      "teamId": "engineering-team",
      "teamName": "Engineering Team",
      "seats": [
        {
          "id": "seat-abc",
          "planSlug": "professional",
          "username": "john",
          "assignedAt": "2024-01-15T10:30:00Z",
          "weeklyBudget": 100,
          "weeklyCostUsed": 45.50,
          "sessionBudget": 50,
          "sessionCostUsed": 12.25
        }
      ],
      "createdAt": "2024-01-15T00:00:00Z"
    }
  ]
}

Notes:

• Enriches License Manager data with local team ownership information
• Returns subscriptions with nested seat details
• Requires admin/superuser permissions

---

POST /api/subscriptions

Create a new subscription with initial seats.

Authentication: Required (superuser)

Pre-blocks: Permission check for admin access

Request Body:

Field	Type	Required	Description
cardId	string	Yes	QuickBooks card token
billingCycle	string	No	Billing cycle: monthly, annual (default: monthly)
seats	array	Yes	Array of seat requests (min: 1)

Seat Request Object:

Field	Type	Required	Description
planSlug	string	Yes	Plan slug (e.g., professional, enterprise)
quantity	integer	Yes	Number of seats (1-100)

Example Request:

{
  "cardId": "qb-card-token-xyz",
  "billingCycle": "monthly",
  "seats": [
    {
      "planSlug": "professional",
      "quantity": 10
    },
    {
      "planSlug": "enterprise",
      "quantity": 5
    }
  ]
}

Response:

{
  "subscription": {
    "id": "sub-456",
    "status": "active",
    "billingCycle": "monthly",
    "amount": 750.00,
    "taxes": 67.50,
    "cardLast4": "4242",
    "nextBillingDate": "2024-02-15T00:00:00Z",
    "seats": [
      {
        "id": "seat-xyz",
        "planSlug": "professional",
        "weeklyBudget": 100,
        "sessionBudget": 50,
        "exp": 1739548800,
        "sig": "signature-hash"
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Process:

1. Validates plan slugs and purchasability
2. Calculates total amount based on plan pricing
3. Gets tax estimate from billing system
4. Creates subscription via License Manager
5. Stores seat records locally with LM signatures
6. Returns subscription with seat details

Errors:

• 400 - Invalid plan slug or non-purchasable plan
• 403 - Admin access required
• 502 - License Manager or billing system error

---

GET /api/subscriptions/{id}

Get a single subscription by ID.

Authentication: Required (superuser)

Pre-blocks: Permission check for admin access

Response:

{
  "id": "sub-123",
  "status": "active",
  "billingCycle": "annual",
  "amount": 5000.00,
  "taxes": 450.00,
  "cardLast4": "4242",
  "nextBillingDate": "2025-01-15T00:00:00Z",
  "seats": [],
  "createdAt": "2024-01-15T00:00:00Z"
}

Errors:

• 404 - Subscription not found
• 403 - Admin access required
• 502 - License Manager error

---

PUT /api/subscriptions/{id}

Update a subscription (change payment card or billing cycle).

Authentication: Required (superuser)

Pre-blocks: Permission check for admin access

Request Body:

Field	Type	Description
cardId	string | null	New QuickBooks card token
billingCycle	string | null	New billing cycle: monthly, annual

Example Request:

{
  "cardId": "qb-card-token-new",
  "billingCycle": "annual"
}

Response:

Returns the updated subscription object.

Errors:

• 404 - Subscription not found
• 403 - Admin access required
• 502 - License Manager error

---

DELETE /api/subscriptions/{id}

Cancel a subscription.

Authentication: Required (superuser)

Pre-blocks: Permission check for admin access

Response:

{
  "success": true
}

Side Effects:

• Cancels subscription in License Manager
• Stops future billing
• Seats remain active until current billing period ends
• Does not immediately revoke seat assignments

Errors:

• 404 - Subscription not found
• 403 - Admin access required
• 502 - License Manager error

---

Subscription Lifecycle

1. Creation - Admin purchases seats with payment card
2. Active - Seats can be assigned to users
3. Billing - Recurring charges based on billing cycle
4. Updates - Change card or billing cycle
5. Cancellation - Stop future billing, seats expire at period end

Plan Types

Common plan slugs:

• starter - Basic AI access
• professional - Standard business use
• enterprise - Advanced features and higher budgets

Each plan has different pricing for monthly vs. annual billing cycles.

Related APIs

• AI Seats - Assign and manage AI seats
• Teams - Team management for subscription ownership