Using The Cli
The ducto command-line tool lets you manage your credit pricing configuration
Pricing Basics
Every AI-powered application needs to answer the same fundamental question: how many credits does this request cost? Without a consistent pricing foundation, costs become opaque - different engineers hard-code different rates in different places, audit trails vanish, and changing your pricing requires a code deployment.
Credit Lifecycle
Credits flow through a lifecycle: they are added, reserved, deducted, and sometimes refunded. Understanding this lifecycle is critical to building reliable credit systems that prevent race conditions and double-spending.
Plans And Allowances
Most SaaS products offer pricing tiers - Free, Pro, Enterprise - each with a free monthly allowance of credits. ducto tracks per-user plan assignments and monthly usage windows, automatically falling back to the user's credit balance when the free allowance is consumed.
Analytics
Raw credit transactions are a stream of individual events — user X deducted Y credits at time Z. That is hard to read at a glance. ducto's analytics queries aggregate these events into meaningful summaries: total spend per user, breakdown by model, daily trends, and overall statistics. These queries are the foundation for customer-facing dashboards, internal cost analysis, and anomaly detection.
Spend Caps
Without spend caps, a single bug or runaway loop can drain a user's entire credit balance in seconds. Spend caps act as safety valves — they limit how many credits a user can consume in a given period, protecting both the user and the platform operator from unexpected costs.
Teams
Individual user balances work well for B2C products where each user pays for themselves. But B2B SaaS needs team accounts — one company with multiple users sharing a single credit pool. ducto's team feature lets you create shared balances, add members, enforce per-user spend caps, and track who spent what. Think of it like a shared bank account with individual debit card limits.
Events
Credit operations are useful on their own, but often you need to react to them — send a Slack alert when a user's balance runs low, update an analytics dashboard on each deduction, or trigger an auto top-up. ducto's event system follows the observer pattern: you emit events when operations happen, and registered handlers react asynchronously.
Custom Store
ducto ships with two store implementations reservations, deductions, refunds, analytics, team pools, spend caps, and credit expiry.
Expression Evaluator
Pricing formulas in ducto are plain strings: inputtokens * 5 + outputtokens * 15. But executing arbitrary strings as code is dangerous -- that is how injection attacks happen. A naive approach would use eval() to turn a string into a number, but eval() can execute any Python expression, including calls to import (to import the os module), open() (to read files), or globals() (to inspect runtime state). This is like giving a stranger the keys to every room in your house.
Credit Expiry
Free trial credits should expire after 14 days. Purchased credits might expire in 12 months. Promotional bonuses may expire in 60 days. ducto's credit expiry feature handles all of these scenarios with a single sweepexpiredcredits() function. The pattern is simple: when you add credits to a user's balance, you can set an optional expires_at timestamp. If you set it, a background sweep job finds all expired grants and deducts them from the user's available balance.