Quotas & Payments

These endpoints power the billing and monetization system, enabling you to:

• Track user API usage

• Manage and top-up token quotas

• Integrate with payments (e.g., Stripe, Paddle)

🧾 Data Model Highlights

• Quotas are created via payments (e.g., Stripe webhook)

• Usage logs store token consumption, cost, and endpoint history

• All monetary fields are Decimal-typed and validated to 2–4 decimal places

---

🔸 POST /quota – Create Quota Entry (Admin/Internal)

Creates a new token quota (typically triggered by a payment event).

📥 Request:

{
  "api_name": "chat",
  "purchase_amount_usd": 49.99,
  "token_purchased": 10000,
  "notes": "Monthly subscription"
}

🔐 Auth Required: ✅ Yes (Admin/Internal Service)

📤 Response:

{
  "quota_id": "uuid",
  "api_name": "chat",
  "purchase_amount_usd": 49.99,
  "token_purchased": 10000,
  "purchase_date": "2025-07-04T12:00:00Z"
}

---

✅ cURL:

curl -X POST https://api.yourdomain.com/quota \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "api_name": "chat",
    "purchase_amount_usd": 49.99,
    "token_purchased": 10000,
    "notes": "Monthly subscription"
  }'

✅ JavaScript (fetch):

await fetch("https://api.yourdomain.com/quota", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + adminToken,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    api_name: "chat",
    purchase_amount_usd: 49.99,
    token_purchased: 10000,
    notes: "Monthly subscription"
  })
});

---

🔸 GET /quota – List All Quotas

Retrieve all quota records. Supports pagination with skip and limit.

🔐 Auth Required: ✅ Yes

✅ cURL:

curl -X GET "https://api.yourdomain.com/quota?skip=0&limit=20" \
  -H "Authorization: Bearer <admin_token>"

✅ JavaScript:

await fetch("https://api.yourdomain.com/quota?skip=0&limit=20", {
  headers: { Authorization: "Bearer " + adminToken }
});

---

🔸 GET /quota/{quota_id} – View a Specific Quota

Returns full details of a quota record.

🔐 Auth Required: ✅ Yes

✅ cURL:

curl -X GET https://api.yourdomain.com/quota/<quota_id> \
  -H "Authorization: Bearer <admin_token>"

---

🔸 PUT /quota/{quota_id} – Update Quota

Used to adjust quota after plan changes or manual top-ups.

📥 Request:

{
  "purchase_amount_usd": 99.99,
  "notes": "Upgraded to 25K plan"
}

✅ cURL:

curl -X PUT https://api.yourdomain.com/quota/<quota_id> \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "purchase_amount_usd": 99.99,
    "notes": "Upgraded to 25K plan"
  }'

---

🔸 DELETE /quota/{quota_id} – Remove a Quota Entry

Deletes a quota record. Reserved for internal or admin actions.

🔐 Auth Required: ✅ Yes (Admin only)

✅ cURL:

curl -X DELETE https://api.yourdomain.com/quota/<quota_id> \
  -H "Authorization: Bearer <admin_token>"

---

📌 Usage Notes

• These APIs are typically integrated with your billing dashboard, subscription plans, or webhook events from payment providers.

• Each quota is linked to a user_id, and tracked against their actual usage (see api_usage).

• Token consumption is recorded separately (we can document POST /usage next if needed).