How Alguna Works

Alguna runs the whole path from priced offer to recognised revenue in one system: quoting, pricing and packaging, subscription management, usage metering, credits, invoicing, payment collection, and revenue recognition. Most billing tools cover one segment of that path and hand off the rest. Alguna’s model only makes sense once you see the whole chain, because the same objects carry through every stage — a price you configure once is the price that rates usage, lands on the invoice, drives collection, and produces the revenue schedule.

---

​

The chain

Each stage below is self-contained: read only the one you need.

---

​

1. Catalog — what you sell

Products are the things you sell. A product declares how it is charged, not how much: A metered product also carries metric_ids, linking it to the billable metrics that measure it. Prices attach to a product (product_id) and carry the actual money. A price has a type and one matching pricing-model object — for example type: "tiered" with a tiered_pricing_model. Eleven types are available; see Pricing models. Prices also carry the guardrails that most billing systems push into custom code: minimum_spend, maximum_spend, discount, and trial_period_days. Bundles group prices that are sold together, so a multi-price offer can be reused as one unit.

---

​

2. Offer — what you propose

A plan is a reusable, fully-specified offer: items (the priced things), plus the commercial terms that travel with them — contract_duration and contract_period_type, renewal_period_type and auto_renew, trial_period_days, discount, minimum_spend and maximum_spend, price_escalation for ramped deals, entitlements, and invoice_settings. Plans serve both go-to-market motions:

• Self-serve (PLG) — a plan is what a buyer selects in checkout. The offer is fixed, and the subscription is created without a human in the loop.
• Sales-led — a plan is the starting point a rep negotiates from. Quotes, approval routing and e-signature are handled in the dashboard (Quotes); the signed quote becomes the subscription.

Both motions converge on the same subscription object, which is why a company running hybrid motions does not need two billing systems.

---

​

3. Subscription — what was agreed

A subscription binds a customer to an offer. It references customer_id, optionally the plan_id it came from, and carries items, contract, billing, renewal and currency. The part worth understanding before you build anything: subscriptions are versioned. A subscription has a current_version_id and a history of versions. A version is created as a draft, edited freely, and then published to take effect. Nothing you do to a draft affects billing until you publish it. This is why mid-term changes are safe here. An upgrade, a re-negotiation, an added product or a corrected term is a new version — reviewable before it is real, and permanently auditable after. The subscription also exposes pending_changes, so you can see what is queued. Entitlements answer “what is this customer allowed to do?” and come in four shapes: boolean (a feature is on), number (a quota), string (a tier label), and credit_allocation (an included credit balance). Read them per customer or per subscription to gate your product.

---

​

4. Usage — what actually happened

For metered products, Alguna needs to know what the customer consumed.

1. Define a billable metric — the unit you charge for and how raw events roll up into it.
2. Send events to POST /events as usage occurs. Ingestion is idempotent, so retries are safe.
3. Rating happens against the price, using the metric ids on the product or price.

See Send usage for limits and payload shape.

---

​

5. Credits — paying before consuming

Credits are how prepaid balances work: a customer buys capacity up front and draws it down.

• A wallet holds a balance for a customer in one currency, optionally scoped to specific product_ids.
• A wallet grant adds to that balance. Grants can be monetary or denominated in units.
• Consumption draws the balance down as usage is rated.

Alguna also supports checking credit before the work happens, not only reconciling it afterwards: This matters for products where an expensive operation should not start unless the customer can pay for it — inference calls, long-running jobs, metered compute. You describe the work as the events it will produce, and the response tells you what it prices to.

---

​

6. Invoice — what is owed

At the end of a billing period (or on demand) Alguna produces an invoice: subscription charges, rated usage, credits applied, discounts, and tax. Invoices move through an explicit lifecycle rather than a binary paid/unpaid flag: draft → upcoming → pending_approval → scheduled → processing → issued → paid with void, canceled and overdue as terminal or exception states. The pending_approval state exists because enterprise billing often requires a human to sign off before an invoice reaches a customer. See Approval workflows. Corrections are first-class: credit notes adjust an issued invoice, and refunds return money already collected. Neither requires deleting or rewriting history.

---

​

7. Collection and revenue — closing the loop

Payments record money received against invoices. When payment fails or is late, collections and dunning drive retries and outreach. Revenue schedules convert billed amounts into recognised revenue over time, available per subscription, per customer, and per legal entity. This is what makes the loop end-to-end: the same contract that produced the invoice produces the revenue schedule, with no re-keying between billing and finance. Legal entities are the sellers of record — each keeps its own contracts, payments and tax liability, and revenue schedules can be read per legal entity, so a group billing from several entities runs one catalog without mixing books. A merchant is different: a display identity for a business you sell on behalf of. Invoices and receipts carry the merchant’s name and logo, while your legal entity remains the seller of record; a merchant has no tax or legal configuration of its own.

---

​

Object reference

---

​

Where to go next