> ## Documentation Index > Fetch the complete documentation index at: https://alguna.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # How Alguna Works > The end-to-end quote-to-cash model: how products, prices, plans, subscriptions, usage, invoices, payments and revenue fit together. 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. **Alguna is not a payment processor.** It sits above processors such as Stripe. Alguna decides *what* a customer owes and *when*; the processor moves the money. See [Stripe](/docs/integrations/payments/stripe) and [ACH](/docs/integrations/payments/ach). *** ## The chain ```mermaid theme={null} flowchart LR A[Catalog
products & prices] --> B[Offer
plan / quote] B --> C[Subscription
+ versions] D[Usage
events & metrics] --> C E[Credits
wallets & grants] --> C C --> F[Invoice] F --> G[Payment
& collections] F --> H[Revenue
schedules] ``` 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: | Field | Values | Meaning | | ------------------- | ---------------------- | -------------------------------------------- | | `fee_type` | `fixed`, `metered` | Charged at a flat rate, or by measured usage | | `billing_frequency` | `recurring`, `one-off` | Repeats each period, or charges once | | `payment_terms` | `advance`, `arrears` | Billed before the period, or after it | A metered product also carries `metric_ids`, linking it to the [billable metrics](/docs/billable-metrics/define-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](/docs/pricing/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. Product answers *"what is this and how is it charged?"* Price answers *"how much?"* Keeping them separate is what lets you re-price without redefining the product, and sell the same product at different rates to different segments. *** ## 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](/docs/hosted/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](/docs/quotes/create-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. ```mermaid theme={null} flowchart LR V1[Version 1
published] --> D[Version 2
draft] D -->|publish| V2[Version 2
published] D -->|delete| X[discarded] ``` 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. Use `POST /subscriptions/{id}/changes/preview` to see the financial effect of a change — including proration — **before** committing it. **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](/docs/billable-metrics/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: | Endpoint | Purpose | | -------------------------------- | ----------------------------------------------------------------- | | `POST /credits/check` | Price work before it happens and optionally reserve credit for it | | `POST /credits/track` | Record usage and charge credit for it | | `GET /credits/reservations/{id}` | Read a reservation's state and what has been committed against it | 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. `/credits/check` and `/credits/track` take no credit amount. You send the work; Alguna returns the charges. Do not compute prices client-side and send a total — pricing logic belongs on the server that owns it. *** ## 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](/docs/approvals/overview). 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](/docs/collections/overview) 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 | Object | Belongs to | Key fields | | -------------------- | ----------------- | ------------------------------------------------------------------------------ | | Legal entity | — | seller of record: contract, payment, tax liability, revenue | | Merchant | — | display identity (name, logo) on invoices for a business you sell on behalf of | | Customer | — | contacts, tax config, connected accounts | | Product | — | `fee_type`, `billing_frequency`, `payment_terms`, `metric_ids` | | Price | Product | `type` + one pricing-model object, `metric_ids` | | Bundle | — | `prices` | | Plan | — | `items`, `entitlements`, contract and renewal terms | | Subscription | Customer | `plan_id`, `items`, `current_version_id`, `status` | | Subscription version | Subscription | `draft` → `published` | | Billable metric | — | aggregation over events | | Wallet | Customer | `current_balance`, `currency`, `product_ids` | | Wallet grant | Wallet | amount, monetary or units | | Invoice | Customer | line items, 10-state lifecycle | | Credit note / Refund | Invoice / Payment | corrections | | Revenue schedule | Subscription | recognised revenue over time | *** ## Where to go next The shortest path from zero to a live subscription. All eleven price types, with when to use each. Define a metric and send your first events. Authentication, versioning, and every endpoint.