Subscription Plan Design

Goals and Scope

• Add subscription plans on top of the existing balance-based system for individual users.
• Plan cycles support only weekly and monthly (rolling from the subscription start time).
• Quotas are displayed and tracked in USD, with daily and weekly limits.
• Only responses and Claude messages APIs are supported, with dedicated routes:
  • POST /plan/v1/responses
  • POST /plan/v1/messages
• Plan API keys use the plan- prefix and are isolated from existing ak- keys.
• Payment channel: Alipay only.

Out of scope: no changes to existing /v1/responses or /v1/messages; no org/enterprise purchase; no other payment methods.

Key Rules

• Quota unit: USD.
• Cycle start: subscription effective time T0.
• Daily limit: rolling 24-hour window based on T0.
• Weekly limit: rolling 7-day window based on T0.
• Monthly cycle: EndAt = StartAt + 1 month, not fixed 30 days.
• Auto-renewal is not supported.
• Multiple subscriptions allowed, but the same plan cannot be repurchased before expiration.
• If multiple active subscriptions exist, consumption uses the one with the smallest remaining quota, where remaining is min(remaining today, remaining this week).
• Each user can have only one plan key; it can be reset to generate a new key.
• Only models in the plan allowlist are permitted.
• Plan API keys can only access /plan/v1/*, not /v1/*.
• Unpaid orders can be repeated; purchase is blocked only if a paid, active subscription of the same plan exists.

Terms

• Plan Definition (PlanDefinition): a purchasable plan product.
• Subscription (PlanSubscription): an active instance after purchase.
• Plan Key (PlanApiKey): auth key for plan APIs.
• Usage Bucket (PlanUsageBucket): aggregated USD consumption for daily/weekly windows.

Quota Window Calculation

Define T0 = Subscription.StartAt, Now is request time (UTC).

• Daily window:
  • dayIndex = floor((Now - T0) / 24h)
  • Current day window is [T0 + dayIndex * 24h, T0 + (dayIndex + 1) * 24h)
• Weekly window:
  • weekIndex = floor((Now - T0) / 7d)
  • Current week window is [T0 + weekIndex * 7d, T0 + (weekIndex + 1) * 7d)

Displayed "today usage / weekly usage" is the current bucket AmountUsd.

Monthly cycle rule:

• EndAt = StartAt.AddMonths(1) using calendar month semantics (e.g. Jan 31 + 1 month = Feb 28/29).

API Design

Plan APIs (external)

• POST /plan/v1/responses
• POST /plan/v1/messages

Auth: Authorization: Bearer plan-... (same header shape, different prefix).

Suggested errors:

• 401: invalid or missing key
• 403: invalid/expired subscription or non-individual user
• 400: model not in allowlist
• 402: quota exceeded

Edge Cases and Exceptions

Multi-subscription selection

• If a key is bound to a subscription, only that subscription is used; if invalid, return 403.
• If a key is not bound, select among active subscriptions by smallest remaining quota:
  • remaining = min(remaining today, remaining this week).
  • If tied, prefer the earlier EndAt to avoid waste.
• The same plan (PlanId) cannot be repurchased before expiration; purchase returns 409.

Key management boundaries

• One active key per user; reset revokes the old key and creates a new one.
• plan- keys to /v1/* or ak- keys to /plan/* both return 401.

Subscription lifecycle

• No auto-renewal; on expiry status becomes Expired and consumption is blocked.
• Cancellation rules (refunds or remaining quota) to be defined during implementation; default is no automatic refund.

Codex Usage Guide

Install Codex

npm install -g @openai/codex@latest

Configure Codex

Config path:

Windows

C:\Users\<User>\.codex\config.toml

macOS / Linux

~/.codex/config.toml

Example configuration (plan API):

model = "gpt-5.2"
model_provider = "meteor-api"
disable_response_storage = true
approval_policy = "never"
sandbox_mode = "danger-full-access"

[model_providers.meteor-api]
name = "Meteor API"
base_url = "https://api.routin.ai/plan/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Set API Key

Windows (PowerShell)

setx OPENAI_API_KEY "plan-your-api-key-here"

macOS / Linux

export OPENAI_API_KEY="plan-your-api-key-here"

Verify

codex

You can now use your subscription quota.

Claude Code Usage Guide

Install Claude Code

npm install -g @anthropic-ai/claude-code

Configure Claude Code

Create and edit the config file:

Linux / macOS

nano ~/.claude/settings.json

Windows

cd ~/.claude/
code .

Example configuration (plan API):

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "plan-your-api-key-here",
    "ANTHROPIC_BASE_URL": "https://api.routin.ai/plan/",
    "ANTHROPIC_MODEL": "mimo-v2-flash",
    "ANTHROPIC_SMALL_FAST_MODEL": "mimo-v2-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "mimo-v2-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "mimo-v2-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "mimo-v2-flash"
  },
  "alwaysThinkingEnabled": true
}

Verify

claude --version
claude

You can now use your subscription quota.