Customer Billing

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

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

// Create a customer
const customer = await mr.customers.create({
  external_id: "user_123",        // Your user ID
  email: "user@example.com",
});

console.log(customer.customer.id);                    // ModelRelay customer ID
console.log(customer.subscription?.tier_code ?? ""); // Optional tier code

customer, err := client.Customers.Create(ctx, sdk.CustomerCreateRequest{
    ExternalID: sdk.NewCustomerExternalID("user_123"),
    Email:      "user@example.com",
})
if err != nil {
    return err
}

fmt.Println(customer.Customer.ID) // ModelRelay customer ID
tier := ""
if customer.Subscription != nil {
    tier = customer.Subscription.TierCode.String()
}
fmt.Println(tier) // Optional tier code

use modelrelay::{Client, CustomerCreateRequest};

let customer = client.customers().create(CustomerCreateRequest {
    external_id: "user_123".to_string(),
    email: "user@example.com".to_string(),
    metadata: None,
}).await?;

println!("{}", customer.customer.id); // ModelRelay customer ID
if let Some(subscription) = &customer.subscription {
    println!("{}", subscription.tier_code); // Optional tier code
}

// Creates if not exists, updates if exists
const customer = await mr.customers.upsert({
  external_id: "user_123",
  email: "user@example.com",
});

customer, err := client.Customers.Upsert(ctx, sdk.CustomerUpsertRequest{
    ExternalID: sdk.NewCustomerExternalID("user_123"),
    Email:      "user@example.com",
})

// Creates if not exists, updates if exists
let customer = client.customers().upsert(CustomerUpsertRequest {
    external_id: "user_123".to_string(),
    email: "user@example.com".to_string(),
    metadata: None,
}).await?;

const customers = await mr.customers.list();

for (const customer of customers) {
  console.log(`${customer.external_id}: ${customer.tier_code}`);
}

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

for _, customer := range customers {
    fmt.Printf("%s: %s\n", customer.ExternalID, customer.TierCode)
}

let customers = client.customers().list().await?;

for customer in customers {
    println!("{}: {}", customer.external_id, customer.tier_code);
}

// 1. Customer already exists
const customer = await mr.customers.get("cust_uuid");

// 2. Create checkout session for this customer
const session = await mr.customers.subscribe(customer.customer.id, {
  tier_id: "tier_uuid",
  success_url: "https://myapp.com/success?session={CHECKOUT_SESSION_ID}",
  cancel_url: "https://myapp.com/cancel",
});

// 3. Redirect user to Stripe
window.location.href = session.url;

// 1. Customer already exists
customer, err := client.Customers.Get(ctx, customerUUID)
if err != nil {
    return err
}

// 2. Create checkout session for this customer
session, err := client.Customers.Subscribe(ctx, customer.Customer.ID, sdk.CustomerSubscribeRequest{
    TierID:     uuid.MustParse("tier_uuid"),
    SuccessURL: "https://myapp.com/success?session={CHECKOUT_SESSION_ID}",
    CancelURL:  "https://myapp.com/cancel",
})
if err != nil {
    return err
}

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

use modelrelay::CustomerSubscribeRequest;

// 1. Customer already exists
let customer = client.customers().get(&customer_uuid).await?;

// 2. Create checkout session for this customer
let session = client.customers().subscribe(
    customer.customer.id,
    CustomerSubscribeRequest {
        tier_id: tier_uuid,
        success_url: "https://myapp.com/success?session={CHECKOUT_SESSION_ID}".to_string(),
        cancel_url: "https://myapp.com/cancel".to_string(),
    },
).await?;

// 3. Redirect user to Stripe
// Return session.url to your frontend for redirect

const status = await mr.customers.getSubscription("cust_uuid");

if (status.active) {
  console.log("Subscription active until", status.current_period_end);
} else {
  console.log("No active subscription");
}

status, err := client.Customers.GetSubscription(ctx, customerUUID)
if err != nil {
    return err
}

if status.Active {
    fmt.Println("Subscription active until", status.CurrentPeriodEnd)
} else {
    fmt.Println("No active subscription")
}

let status = client.customers().get_subscription(&customer_uuid).await?;

if status.active {
    println!("Subscription active until {:?}", status.current_period_end);
} else {
    println!("No active subscription");
}

// Frontend: using customer bearer token
const mr = ModelRelay.fromToken(customerToken);

// Create a $25 top-up session
const session = await mr.customers.meTopup({
  amount_cents: 2500,
  success_url: "https://myapp.com/billing?success=true",
  cancel_url: "https://myapp.com/billing",
});

// Redirect to Stripe checkout
window.location.href = session.url;

curl -X POST https://api.modelrelay.ai/api/v1/customers/me/topup \
  -H "Authorization: Bearer mr_ct_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 2500,
    "success_url": "https://myapp.com/billing?success=true",
    "cancel_url": "https://myapp.com/billing"
  }'

// Frontend: using a customer bearer token
const mr = ModelRelay.fromToken(customerToken);

// Get customer's own profile
const me = await mr.customers.me();
console.log(`Tier: ${me.tier_code}`);

// Get usage for current billing period
const usage = await mr.customers.meUsage();

console.log(`Billing period: ${usage.window_start} - ${usage.window_end}`);
console.log(`Requests: ${usage.requests}`);
console.log(`Tokens: ${usage.tokens}`);

// Total cost is always available
const totalCost = usage.total_cost_cents / 100;
console.log(`Total cost: $${totalCost.toFixed(2)}`);

// Spend limit (if configured on tier)
if (usage.spend_limit_cents) {
  console.log(`Spend limit: $${(usage.spend_limit_cents / 100).toFixed(2)}`);
}

// For tiers with spend limits
if (usage.spend_limit_cents) {
  const limit = usage.spend_limit_cents / 100;
  const remaining = (usage.spend_remaining_cents ?? 0) / 100;

  console.log(`Budget: $${totalCost.toFixed(2)} / $${limit.toFixed(2)} used`);
  console.log(`Remaining: $${remaining.toFixed(2)}`);

  if (usage.low) {
    console.log("⚠️ Usage is above 80%");
  }
}

// PAYGO wallet (overage)
if (usage.wallet_balance_cents !== undefined) {
  const balance = usage.wallet_balance_cents / 100;
  const reserved = (usage.wallet_reserved_cents ?? 0) / 100;
  console.log(`Wallet: $${balance.toFixed(2)} (reserved $${reserved.toFixed(2)})`);

  if (usage.overage_enabled) {
    console.log("Overage enabled: PAYGO wallet covers spend overages");
  }
}

// Daily breakdown
for (const day of usage.daily) {
  console.log(`${day.day}: ${day.requests} requests, ${day.tokens} tokens`);
}

// Using a customer bearer token
client, err := sdk.NewClientWithToken(customerToken)
if err != nil {
    return err
}

// Get customer's own profile
me, err := client.Customers.Me(ctx)
if err != nil {
    return err
}
fmt.Printf("Tier: %s\n", me.TierCode)

// Get usage for current billing period
usage, err := client.Customers.MeUsage(ctx)
if err != nil {
    return err
}

fmt.Printf("Billing period: %s - %s\n", usage.WindowStart, usage.WindowEnd)
fmt.Printf("Requests: %d\n", usage.Requests)
fmt.Printf("Tokens: %d\n", usage.Tokens)

// Total cost is always available
totalCost := float64(usage.TotalCostCents) / 100
fmt.Printf("Total cost: $%.2f\n", totalCost)

// Spend limit (if configured on tier)
if usage.SpendLimitCents != nil {
    fmt.Printf("Spend limit: $%.2f\n", float64(*usage.SpendLimitCents) / 100)
}

// For tiers with spend limits
if usage.SpendLimitCents != nil {
    limit := float64(*usage.SpendLimitCents) / 100
    remaining := float64(0)
    if usage.SpendRemainingCents != nil {
        remaining = float64(*usage.SpendRemainingCents) / 100
    }

    fmt.Printf("Budget: $%.2f / $%.2f used\n", totalCost, limit)
    fmt.Printf("Remaining: $%.2f\n", remaining)

    if usage.Low != nil && *usage.Low {
        fmt.Println("⚠️ Usage is above 80%")
    }
}

// PAYGO wallet (overage)
if usage.WalletBalanceCents != nil {
    balance := float64(*usage.WalletBalanceCents) / 100
    reserved := float64(0)
    if usage.WalletReservedCents != nil {
        reserved = float64(*usage.WalletReservedCents) / 100
    }
    fmt.Printf("Wallet: $%.2f (reserved $%.2f)\n", balance, reserved)

    if usage.OverageEnabled != nil && *usage.OverageEnabled {
        fmt.Println("Overage enabled: PAYGO wallet covers spend overages")
    }
}

// Daily breakdown
for _, day := range usage.Daily {
    fmt.Printf("%s: %d requests, %d tokens\n", day.Day, day.Requests, day.Tokens)
}

use modelrelay::{Client, Config, AccessToken};

// Using a customer bearer token
let client = Client::new(Config {
    access_token: Some(AccessToken::parse(&customer_token)?),
    ..Default::default()
})?;

// Get customer's own profile
let me = client.customers().me().await?;
println!("Tier: {}", me.tier_code);

// Get usage for current billing period
let usage = client.customers().me_usage().await?;

println!("Billing period: {} - {}", usage.window_start, usage.window_end);
println!("Requests: {}", usage.requests);
println!("Tokens: {}", usage.tokens);

// Total cost is always available
let total_cost = usage.total_cost_cents as f64 / 100.0;
println!("Total cost: ${:.2}", total_cost);

// Spend limit (if configured on tier)
if let Some(limit) = usage.spend_limit_cents {
    println!("Spend limit: ${:.2}", limit as f64 / 100.0);
}

// For tiers with spend limits
if let Some(limit) = usage.spend_limit_cents {
    let limit = limit as f64 / 100.0;
    let remaining = usage.spend_remaining_cents.unwrap_or(0) as f64 / 100.0;

    println!("Budget: ${:.2} / ${:.2} used", total_cost, limit);
    println!("Remaining: ${:.2}", remaining);

    if usage.low.unwrap_or(false) {
        println!("⚠️ Usage is above 80%");
    }
}

// PAYGO wallet (overage)
if let Some(balance) = usage.wallet_balance_cents {
    let reserved = usage.wallet_reserved_cents.unwrap_or(0) as f64 / 100.0;
    println!("Wallet: ${:.2} (reserved ${:.2})", balance as f64 / 100.0, reserved);

    if usage.overage_enabled.unwrap_or(false) {
        println!("Overage enabled: PAYGO wallet covers spend overages");
    }
}

// Daily breakdown
for day in &usage.daily {
    println!("{}: {} requests, {} tokens", day.day, day.requests, day.tokens);
}

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

try {
  const response = await mr.responses.text(
    "claude-sonnet-4-5",
    "You are helpful.",
    "Hello!"
  );
} catch (error) {
  if (error instanceof APIError && error.status === 402) {
    // Customer has exceeded their quota
    console.log("Quota exceeded. Please upgrade your plan.");
    // Show upgrade prompt to user
  } else {
    throw error;
  }
}

response, err := client.Responses.Create(ctx, req)
if err != nil {
    var apiErr sdk.APIError
    if errors.As(err, &apiErr) && apiErr.Status == 402 {
        // Customer has exceeded their quota
        fmt.Println("Quota exceeded. Please upgrade your plan.")
        // Show upgrade prompt to user
        return
    }
    return err
}

use modelrelay::errors::{Error, APIError};

match ResponseBuilder::text_prompt("You are helpful.", "Hello!")
    .model("claude-sonnet-4-5")
    .send_text(&client.responses())
    .await
{
    Ok(response) => println!("{}", response),
    Err(Error::API(APIError { status: 402, .. })) => {
        // Customer has exceeded their quota
        println!("Quota exceeded. Please upgrade your plan.");
        // Show upgrade prompt to user
    }
    Err(e) => return Err(e.into()),
}