Tiers API

Tiers define pricing plans for your customers. Each tier specifies:

• Which models customers can access
• Usage limits (spend caps)
• Subscription pricing (for paid tiers)
• Per-model token pricing

Quick Reference

GET    /api/v1/tiers              List tiers
GET    /api/v1/tiers/:id          Get a tier
POST   /api/v1/tiers/:id/checkout Create checkout session (paid tiers)

Authentication

All tier endpoints accept:

• Publishable key (mr_pk_*): Read-only access to list and get tiers
• Secret key (mr_sk_*): Full access including checkout sessions

List Tiers

GET /api/v1/tiers

Returns all tiers configured for the project.

Response

{
  "tiers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": "550e8400-e29b-41d4-a716-446655440001",
      "tier_code": "free",
      "display_name": "Free",
      "spend_limit_cents": 500,
      "models": [...],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "project_id": "550e8400-e29b-41d4-a716-446655440001",
      "tier_code": "pro",
      "display_name": "Pro",
      "spend_limit_cents": 5000,
      "models": [...],
      "billing_provider": "stripe",
      "billing_price_ref": "price_1234567890",
      "price_amount_cents": 2900,
      "price_currency": "usd",
      "price_interval": "month",
      "trial_days": 14,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Example

curl https://api.modelrelay.ai/api/v1/tiers \
  -H "Authorization: Bearer mr_pk_..."

import { ModelRelay } from "@modelrelay/sdk";

const mr = ModelRelay.fromPublishableKey(process.env.MODELRELAY_PUBLISHABLE_KEY!);

const tiers = await mr.tiers.list();
for (const tier of tiers) {
  console.log(`${tier.display_name}: $${tier.spend_limit_cents / 100}/mo limit`);
}

tiers, err := client.Tiers.List(ctx)
if err != nil {
    return err
}

for _, tier := range tiers {
    fmt.Printf("%s: $%.2f/mo limit\n", tier.DisplayName, float64(tier.SpendLimitCents)/100)
}

Get Tier

GET /api/v1/tiers/:id

Returns a single tier by ID.

Response

{
  "tier": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "project_id": "550e8400-e29b-41d4-a716-446655440001",
    "tier_code": "pro",
    "display_name": "Pro",
    "spend_limit_cents": 5000,
    "models": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "tier_id": "550e8400-e29b-41d4-a716-446655440000",
        "model_id": "claude-sonnet-4-20250514",
        "model_display_name": "Claude Sonnet 4",
        "description": "Fast, capable model for most tasks",
        "capabilities": ["text", "vision", "tool_use"],
        "context_window": 200000,
        "max_output_tokens": 8192,
        "deprecated": false,
        "input_price_per_million_cents": 300,
        "output_price_per_million_cents": 1500,
        "is_default": true,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ],
    "billing_provider": "stripe",
    "billing_price_ref": "price_1234567890",
    "price_amount_cents": 2900,
    "price_currency": "usd",
    "price_interval": "month",
    "trial_days": 14,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Example

curl https://api.modelrelay.ai/api/v1/tiers/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer mr_pk_..."

const tier = await mr.tiers.get("550e8400-e29b-41d4-a716-446655440000");
console.log(`${tier.display_name} includes ${tier.models.length} models`);

tier, err := client.Tiers.Get(ctx, uuid.MustParse("550e8400-e29b-41d4-a716-446655440000"))
if err != nil {
    return err
}

fmt.Printf("%s includes %d models\n", tier.DisplayName, len(tier.Models))

Create Checkout Session

POST /api/v1/tiers/:id/checkout

Creates a Stripe checkout session for a paid tier. This enables “Stripe-first” flows where users subscribe before authenticating. After checkout completes, a customer record is created with the email collected by Stripe.

Requires secret key (mr_sk_*).

Request Body

Response

Example

curl -X POST https://api.modelrelay.ai/api/v1/tiers/550e8400-e29b-41d4-a716-446655440000/checkout \
  -H "Authorization: Bearer mr_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://myapp.com/success",
    "cancel_url": "https://myapp.com/pricing"
  }'

const mr = ModelRelay.fromSecretKey(process.env.MODELRELAY_SECRET_KEY!);

const session = await mr.tiers.checkout("550e8400-e29b-41d4-a716-446655440000", {
  success_url: "https://myapp.com/success",
  cancel_url: "https://myapp.com/pricing",
});

// Redirect user to Stripe
res.redirect(session.url);

session, err := client.Tiers.Checkout(ctx, uuid.MustParse("550e8400-e29b-41d4-a716-446655440000"), sdk.TierCheckoutRequest{
    SuccessURL: "https://myapp.com/success",
    CancelURL:  "https://myapp.com/pricing",
})
if err != nil {
    return err
}

// Redirect user to Stripe
http.Redirect(w, r, session.URL, http.StatusSeeOther)

Response

{
  "session_id": "cs_test_a1b2c3d4e5f6g7h8i9j0",
  "url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3..."
}

Tier Object

TierCode Format

The tier_code field must:

• Start with a lowercase letter
• Contain only lowercase letters, numbers, hyphens, and underscores
• Be 1-64 characters long
• Pattern: ^[a-z][a-z0-9_-]*$

Examples: free, pro, enterprise, team-monthly, api_basic

TierModel Object

Each tier contains an array of models with per-model pricing:

Token Pricing Example

Token prices are specified in cents per million tokens:

• input_price_per_million_cents: 300 = $3.00 per million input tokens
• output_price_per_million_cents: 1500 = $15.00 per million output tokens

Usage Limits

The spend_limit_cents field defines the maximum monthly spend for customers on this tier. When a customer’s accumulated token costs reach this limit, further requests are rejected with a 402 Payment Required error.

Limit Configuration Examples

A spend_limit_cents of 0 means unlimited usage.

Spend Calculation

Customer spend is calculated based on actual token usage:

request_cost = (input_tokens × input_price / 1,000,000) + (output_tokens × output_price / 1,000,000)

For example, with Claude Sonnet 4 pricing ($3/1M input, $15/1M output):

• 1,000 input tokens + 500 output tokens = $0.003 + $0.0075 = ~$0.01

Free vs Paid Tiers

Free Tiers

Free tiers have no Stripe integration:

• No billing_price_ref, price_amount_cents, or price_interval
• Customers are assigned directly via the API
• Usage is tracked against spend_limit_cents

Paid Tiers

Paid tiers integrate with Stripe for billing:

• billing_price_ref links to a provider recurring price
• price_amount_cents and price_interval define subscription cost
• Customers subscribe via Stripe checkout
• trial_days enables free trials before billing begins

Error Codes

Next Steps

• Customers API - Assign customers to tiers
• Responses API - Make AI requests with tier-based billing
• Authentication - API key types and customer tokens