API & MCP documentation

Three steps take you from an empty account to credits being consumed by your own app. Each step is useful on its own.

1. 1

   Create a plan

   A plan is a bundle of credits at a price: “Algebra Tutoring, 10 credits, $100”.

   Create a plan
2. 2

   Enroll a customer

   Send a checkout link or grant complimentary credits. The balance belongs to that customer and that plan.

   See customers
3. 3

   Consume a credit

   Call the consume endpoint with a machine key whenever the customer uses the service.

   Generate a key

Litesubs is a remote MCP server. Add this endpoint to a compatible client and your assistant can manage plans, enroll customers and grant credits for you:

https://litesubs.com/api/mcp

{
  "mcpServers": {
    "litesubs": {
      "type": "http",
      "url": "https://litesubs.com/api/mcp"
    }
  }
}

1. Choose a remote HTTP MCP connection in your client and paste the endpoint above.
2. Sign in to Litesubs and review the requested permissions.
3. Approve access, then ask your assistant to create a plan, enroll a student, or grant credits.

Example prompts: Create an Algebra plan with 10 credits for $100. Enroll ana@example.com in Algebra and give me the payment link.

The server implements the stateless MCP 2026-07-28 profile with CIMD client identification. Legacy session-based and DCR-only clients are not currently supported; if your client cannot connect, check its protocol support.

Creator tools: list/get/create/update plans, list/get customers, enroll customers, grant credits, and list transactions. The consumption tool is available to machine keys only. No payout or refund tools are exposed. Scope failures return structured tool errors.

Creator operations: use OAuth through your MCP client. The scopes are plans:read, plans:write, customers:read, customers:write, and billing:read. An OAuth access token can also call REST endpoints with Authorization: Bearer <token>.

Machine consumption: generate an API token and send it in the x-api-key header. Tokens only consume credits; they cannot edit plans, grant credits, or read billing history. Keep them on your backend, never in public frontend code.

Authorization: Bearer <oauth token>   # creator operations
x-api-key: <machine token>            # consumption only

Tokens are shown once when generated. Save them securely; revoke and replace a lost or exposed token. Token expiration and rate limits are enforced on verification.

Base URL: https://litesubs.com. Send JSON bodies with Content-Type: application/json. List routes accept limit (1–100, default 50) and offset.

Plan creation takes {"name":"Algebra","price":100,"credits":10,"currency":"usd"}. Input prices are in major units ($100); returned prices are in minor units (10000 cents). Currencies: USD and EUR. Updating a plan does not change existing balances.

curl -X POST 'https://litesubs.com/api/v1/plans' \
  -H 'Authorization: Bearer <oauth token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Algebra","price":100,"credits":10,"currency":"usd"}'

Errors return error, code, and optional details or fieldErrors. Expect 400 for invalid input, 401 for failed authentication, 403 for missing access, 404 for missing resources, and 409 for ambiguous identifiers or credit conflicts.

Balances belong to a customer and a specific plan, not a shared wallet. Use exact names, emails, or IDs; ambiguous names require an explicit ID. Credits cannot go negative.

curl -X POST 'https://litesubs.com/api/v1/credits/consume' \
  -H 'x-api-key: <your token>' \
  -H 'Content-Type: application/json' \
  -d '{"customer":"ana@example.com","plan":"Algebra","amount":1,"reason":"Lesson completed","idempotency_key":"booking_8812"}'

A stable idempotency_key is required for consumption. Reuse it when retrying the same event: the original receipt is returned without another debit. A different payload using the same key returns a conflict. Grants accept an optional key.

reason is required and visible in the customer ledger. Set dry_run: true to preview a before/after balance without writing or reserving a key. Receipts contain transactionId, before, after, dryRun, and replayed.

{
  "transactionId": "f2c1…",
  "before": 10,
  "after": 9,
  "dryRun": false,
  "replayed": false
}

Send {"customer":"ana@example.com","plan":"Algebra","mode":"invoice"} to /api/v1/enrollments, or use enroll_customer in MCP. Invoice mode is the default; it returns a checkout link and grants credits only after payment.

curl -X POST 'https://litesubs.com/api/v1/enrollments' \
  -H 'Authorization: Bearer <oauth token>' \
  -H 'Content-Type: application/json' \
  -d '{"customer":"ana@example.com","plan":"Algebra","mode":"invoice"}'

For complimentary access, set mode: "comp" and provide a reason. An existing enrollment cannot be comped again; use a separate credit grant.

If the student has no account, the result is invited with an expiring claim link. Complimentary credits are granted once on claim. No email is sent. Forward the returned invitation or payment link yourself.