autumn-add-usage-tracking

Always consult docs.useautumn.com for code examples and latest API.

Autumn tracks feature usage and enforces limits. Backend checks required for security.

---

Quick Reference

Core Pattern

check → work → track

Check Response

| Field | Description | |-------|-------------| | allowed | Can customer proceed | | balance | Units remaining | | included_usage | Total usage included in plan | | unlimited | No limit enforced |

Feature Types

| Type | Behavior | |------|----------| | boolean | Access granted or denied | | metered | Usage tracked against limit | | credit_system | Pool for multiple features |

---

Security Model

| Layer | Purpose | Trust | |-------|---------|-------| | Frontend | UX (show/hide UI) | Untrusted | | Backend | Enforcement | Required |

---

Backend Implementation

import { Autumn } from "autumn-js";

const autumn = new Autumn({ secretKey: process.env.AUTUMN_SECRET_KEY });

// 1. Check
const { data } = await autumn.check({ customer_id, feature_id: "api_calls" });
if (!data.allowed) return { error: "Limit reached" };

// 2. Work
const result = await doWork();

// 3. Track
await autumn.track({ customer_id, feature_id: "api_calls", value: 1 });
return result;

from autumn import Autumn

autumn = Autumn('am_sk_test_xxx')

response = await autumn.check(customer_id="user_123", feature_id="api_calls")
if not response.allowed:
    raise HTTPException(403, "Limit reached")

result = await do_work()
await autumn.track(customer_id="user_123", feature_id="api_calls", value=1)

---

React Implementation

import { useCustomer } from "autumn-js/react";

const { check, refetch } = useCustomer();

const handleAction = async () => {
  const { data } = await check({ featureId: "messages" });
  if (!data?.allowed) {
    showUpgradePrompt();
    return;
  }
  
  await performAction();
  await refetch();
};

---

Displaying Usage

const { customer } = useCustomer();
const feature = customer?.features?.api_calls;

<p>{feature?.balance} / {feature?.included_usage}</p>

---

Credit Systems

Track the underlying metered feature, not the credit system:

// Config: credits → api_calls (1), image_gen (10)

// Wrong
await autumn.track({ customer_id, feature_id: "credits", value: 10 });

// Right - Autumn deducts 10 credits automatically
await autumn.track({ customer_id, feature_id: "image_gen", value: 1 });

---

Common Gotchas

1. Track after success - Only track if work completes successfully
2. Backend required - Frontend checks can be bypassed
3. Credit systems - Track metered features, not the credit pool
4. Idempotency - Use idempotency_key to prevent double-counting
5. Batch tracking - Pass higher value for bulk operations

---

Resources

• Check Docs
• Track Docs
• Credit Systems
• LLMs.txt