shopify-ai-backup/dodo-unlimited.md

Dodo Payments Usage-Based Billing Setup Guide

This guide explains how to configure usage-based billing (pay-per-token) in Shopify AI App Builder with Dodo Payments.

Overview

Usage-based billing allows users to pay only for the exact number of tokens they consume over their plan limit. When enabled, the system sends usage events to Dodo meters and charges the exact overage automatically each billing cycle. Administrators can set custom rates per currency through the admin panel.

---

How It Works

1. User enables unlimited usage in their account settings
2. Tokens are consumed and tracked against the plan limit
3. Overage tokens are metered and sent to Dodo usage events
4. Billing is exact - users pay only for overage tokens
5. Automatic billing occurs each cycle via Dodo usage-based billing

---

Configuration Steps

1) Admin Panel - Set Token Rates

1. Navigate to /admin/plans as an admin
2. Scroll to "Token usage rates" section
3. Set the rate per 1,000,000 tokens for each currency (USD, GBP, EUR)
4. Click "Save changes"

Example Rates:

• USD: $2.50 per 1M tokens (250 cents)
• GBP: £2.00 per 1M tokens (200 cents)
• EUR: €2.50 per 1M tokens (250 cents)

These rates are automatically applied when users consume tokens.

2) Dodo Dashboard - Configure Meter

1. Create a meter with event name matching DODO_USAGE_EVENT_NAME (default: token.usage)
2. Set aggregation to sum over costCents (or your configured cost field)
3. Attach the meter to your subscription product
4. Set unit price to $0.01 / €0.01 / £0.01 if summing costCents

3) User Configuration

Users can configure their billing preferences in /settings:

1. Select currency (USD, GBP, or EUR)
2. Enable unlimited usage checkbox
3. Save changes to activate usage-based billing

---

User Experience

Enabling Unlimited Usage

1. User navigates to /settings
2. User sees "Enable unlimited usage" checkbox in Plan & Billing section
3. User checks the box and selects their preferred currency
4. User clicks "Save changes"
5. System confirms the change

Token Consumption

When unlimited usage is enabled:

• Overage tracking: Only tokens beyond the plan limit are billed
• Precision billing: Users pay exactly the rate set by administrator
• Automatic charges: Dodo bills usage each cycle via meters
• Transparent tracking: Users can see usage in their invoices

---

API Endpoints

Get Token Rates (Admin Only)

GET /api/admin/token-rates
Authorization: Admin session required

Response:

{
  "ok": true,
  "rates": {
    "usd": 250,
    "gbp": 200,
    "eur": 250
  }
}

Update Token Rates (Admin Only)

POST /api/admin/token-rates
Authorization: Admin session required
Content-Type: application/json

{
  "rates": {
    "usd": 250,
    "gbp": 200,
    "eur": 250
  }
}

Response:

{
  "ok": true,
  "rates": {
    "usd": 250,
    "gbp": 200,
    "eur": 250
  }
}

Usage Events (Server-side)

Usage-based billing relies on server-side ingestion of usage events to Dodo. Events are sent automatically when overage tokens are detected.

POST https://<dodo_base_url>/events/ingest
Authorization: Bearer <DODO_API_KEY>
Content-Type: application/json

{
  "events": [
    {
      "event_id": "usage_<uuid>",
      "customer_id": "<dodo_customer_id>",
      "event_name": "token.usage",
      "timestamp": "2026-01-20T00:00:00Z",
      "metadata": {
        "billableTokens": 2500000,
        "costCents": 500,
        "currency": "usd",
        "ratePerMillion": 200,
        "plan": "starter",
        "month": "2026-01"
      }
    }
  ]
}

---

Billing Logic

Token Cost Calculation (Overage Only)

// When user consumes tokens
tokensUsed = numberOfTokensConsumed
previousTotal = bucket.usage
bucket.usage = previousTotal + tokensUsed

planLimit = getPlanTokenLimits(user.plan)
previousOverage = max(0, previousTotal - planLimit)
currentOverage = max(0, bucket.usage - planLimit)
overageDelta = max(0, currentOverage - previousOverage)

userCurrency = user.billingCurrency || 'usd'
rate = tokenRates[userCurrency]  // Cents per 1M tokens
chargeAmount = round((overageDelta * rate) / 1_000_000)

// Send usage event to Dodo meters
sendUsageEvent({
  billableTokens: overageDelta,
  costCents: chargeAmount,
  currency: userCurrency,
  ratePerMillion: rate,
})

Example Scenarios

Scenario 1: User consumes 500,000 tokens over limit at $2.50/M rate

• Rate: 250 cents per 1M tokens
• Overage tokens: 500,000
• Calculation: (500,000 * 250) / 1,000,000 = 125 cents
• Charge: $1.25 (usage event)

Scenario 2: User consumes 2,500,000 tokens over limit at $2.00/M rate

• Rate: 200 cents per 1M tokens
• Overage tokens: 2,500,000
• Calculation: (2,500,000 * 200) / 1,000,000 = 500 cents
• Charge: $5.00 (usage event)

---

Important Notes

1) Rate Configuration

• Admin control: Only administrators can set token rates via admin panel
• Per currency: Separate rates for USD, GBP, and EUR
• Flexible: Rates can be adjusted at any time
• Precision: Calculated in cents/minor units for accuracy

2) Dodo Meter Configuration

• Event name: Must match DODO_USAGE_EVENT_NAME (default: token.usage)
• Aggregation: Use sum over costCents (or your configured cost field)
• Unit price: Set to $0.01 per unit if summing costCents
• Free threshold: Optional; can be used to mirror plan limits if desired

3) Currency Handling

• User selection: Users can choose their preferred currency in settings
• Rate matching: Appropriate rate applied based on user's currency
• Consistency: Events include currency and ratePerMillion

4) Unlimited Usage Flag

• Required: Must be enabled for usage-based billing
• Optional: Users can disable and return to plan-based limits
• Flexible: Can be toggled at any time
• Persistent: Setting saved per user

---

Troubleshooting

Issue: Usage events not billing

Symptom: Tokens over limit are recorded but no charges appear

Solutions:

1. Verify unlimitedUsage is enabled for the user
2. Check the user has a Dodo customer ID and billing email
3. Verify tokenRates are configured in admin panel
4. Ensure Dodo meter event name matches DODO_USAGE_EVENT_NAME
5. Review recordUserTokens() logs for ingest errors

Issue: Rates not applying correctly

Symptom: Charges don't match configured rates

Solutions:

1. Verify rates are saved to token-rates.json
2. Check loadTokenRates() is called on server startup
3. Ensure currency conversion is correct (cents vs dollars)
4. Review token division by 1,000,000 calculation

---

Best Practices

1) Rate Configuration

• Set competitive rates: Align with market prices for token usage
• Update regularly: Adjust for currency exchange rate changes
• Test calculations: Verify rate × tokens = correct charge
• Document changes: Keep record of rate adjustments

2) User Communication

• Clear pricing: Display rates prominently in settings
• Show calculations: Let users see how charge is calculated
• Invoice transparency: Show usage and charges in invoices

3) Monitoring

• Monitor usage events: Track ingest success and meter totals
• Monitor token consumption: Analyze usage patterns by user
• Watch for anomalies: Detect unusual consumption patterns
• Revenue analytics: Compare usage-based vs subscription revenue

4) System Performance

• Batch ingestion: Send usage events in batches where possible
• Error handling: Retry failed usage event ingestion gracefully
• Logging: Track all usage events for audit trails

---

Reference Links

• Dodo Payments API Documentation
• Main Dodo Setup Guide
• Token Usage Implementation
• Payment Flow Documentation

---

Summary

The usage-based billing model provides:

• Exact charging: Users pay only for tokens they actually consume over limit
• Flexible pricing: Administrators can set custom rates per currency
• No limits: Usage can exceed plan limits with automatic billing
• Metered tracking: Usage is reported via Dodo meters
• Simple management: Charges appear automatically in invoices

Users can enable unlimited usage and the system will automatically charge the exact amount for overage tokens based on administrator-set rates.