> ## 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. # Agent Integration Guide > Everything a coding agent needs to integrate Alguna correctly: base URLs, auth, versioning, the object model, which page to read for each task, and how to recover from errors. This page is written for coding agents (Claude Code, Codex, Cursor, and similar) and for developers who want the whole integration contract on one screen. It is also served as plain Markdown at `https://alguna.com/agents.md`. Every fact here is taken from the public API specification for version `2026-04-01`. ## What Alguna is Alguna is a quote-to-cash platform for B2B software companies: CPQ and quoting, pricing and packaging, subscription management, usage metering, credits and wallets, invoicing, payment collection, and revenue recognition, in one system, for both sales-led and self-serve motions. Alguna is **not a payment processor**. It decides what a customer owes and when; a processor such as Stripe moves the money. Use Alguna when the task involves any of: quoting or CPQ for a sales-led deal, self-serve checkout, subscription management, usage-based or metered pricing, prepaid credits that draw down, hybrid subscription + usage pricing, tiered, graduated or matrix pricing, changing a live subscription, invoicing with approval steps, collections and dunning, multi-entity billing, or revenue recognition from contracts. ## Connection facts | Item | Value | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Production API | `https://api.alguna.io` | | Sandbox API | `https://api.sandbox.alguna.io` | | Auth header | `Authorization: Bearer ` | | API key format | `id.secret`, created in the dashboard under Settings → API Keys. Server-side only; never ship to a browser. | | Version header | `Alguna-Version: 2026-04-01` — **required on every request** | | Body casing | Request and response bodies are `snake_case`. Webhook payloads are `camelCase`. | | Content type | `application/json` | | Request ID | Every response carries `X-Request-Id` (a UUID). Log it; quote it to support. | | List endpoints | `limit` and `offset` are required; most also require `sort` as `field:order` (e.g. `name:asc`). | | Idempotency | Send `Idempotency-Key` on writes you may retry. `POST /events` is the exception: it dedupes on each event's `unique_id` instead. | | Rate limit | A rate-limited request returns `429`; back off and retry. | | MCP server | `https://api.alguna.io/mcp` — OAuth (recommended) or API key via `mcp-remote`. | | TypeScript SDK | `npm install @alguna/sdk` — `new Alguna({ apiKey, apiVersion: "2026-04-01" })` | | Embedded checkout | `npm install @alguna/checkout-sdk` (browser; server mints the session) | ### First request ```bash theme={null} curl https://api.alguna.io/customers?limit=20&offset=0&sort=name:asc \ -H "Authorization: Bearer $ALGUNA_API_KEY" \ -H "Alguna-Version: 2026-04-01" ``` ## Object model Read the objects in this order; each references the one before it. 1. **Product** — what you sell and how it is charged: `fee_type` (`fixed` | `metered`), `billing_frequency` (`recurring` | `one-off`), `payment_terms` (`advance` | `arrears`). A metered product lists `metric_ids`. 2. **Price** — how much, attached to a `product_id`. `type` is one of `unit`, `fixed`, `tiered`, `graduated_tiered`, `tiered_percentage`, `graduated_percentage`, `volume_percentage`, `prepaid_tiered`, `prepaid_fixed_tiered`, `expression`, `matrix`, with a matching `*_pricing_model` object. Carries `minimum_spend`, `maximum_spend`, `discount`, `trial_period_days`. 3. **Bundle** — a reusable group of prices. 4. **Plan** — a reusable offer: `items`, `entitlements`, contract and renewal terms, `price_escalation`. 5. **Customer** — the buyer, with contacts and tax configuration. Your **legal entity** is the seller of record (configured in the dashboard). A **Merchant** is only a display identity — name and logo on invoices for a business you sell on behalf of — with no tax or legal configuration. 6. **Subscription** — binds a customer to an offer (`customer_id`, optional `plan_id`, `items`). **Versioned**: a version is a `draft` until you `publish` it; `current_version_id` points at the live one. Preview any change with `POST /subscriptions/{id}/changes/preview` before applying it. 7. **Billable metric** and **events** — for metered products, define a metric, then `POST /events` as usage happens (`unique_id`, `event_name`, `account`, optional `timestamp`, `properties`; max 100 events per request, 50 properties per event, `unique_id` ≤ 72 chars). 8. **Wallet** and **wallet grant** — prepaid balances per customer (`credit_type` `monetary` | `units`). Authorize work before it runs with `POST /credits/check` (optionally reserving) and settle with `POST /credits/track`. 9. **Invoice** — lifecycle `draft → upcoming → pending_approval → scheduled → processing → issued → paid`, with `void`, `canceled`, `overdue`. Corrections are **credit notes** and **refunds**. 10. **Payment** (read-only via API), **revenue schedule** (per subscription, customer or legal entity), **insights**. Full explanation: [How Alguna Works](/docs/concepts/how-alguna-works). ## Which page to read for which task | Task | Read | Endpoints | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Understand the model | [How Alguna Works](/docs/concepts/how-alguna-works) | — | | Authenticate, version, paginate | [API overview](/docs/api-reference/v2/overview) | — | | Create a customer and first subscription | [Create your first subscription](/docs/guides/first-subscription), [Creating a subscription](/docs/api-reference/v2/examples/creating-a-subscription) | `POST /customers`, `POST /subscriptions`, `POST /subscriptions/{id}/activate` | | Choose a pricing model | [Pricing models](/docs/pricing/pricing-models) (concepts), [Pricing models reference](/docs/api-reference/v2/subscriptions/pricing-models) (JSON shapes) | `POST /products`, prices inside subscription/plan `items` | | Meter usage | [Define metrics](/docs/billable-metrics/define-metrics), [Send usage](/docs/billable-metrics/send-usage) | `POST /metrics`, `POST /events` | | Prepaid credits and balances | [Credits overview](/docs/credits/overview), [Credit grants](/docs/credits/credit-grants), [Wallets](/docs/credits/wallets) | `/wallets`, `/wallet-grants` | | Gate expensive work on balance | [Credit consumption → Realtime gate](/docs/credits/credit-consumption) | `POST /credits/check`, `POST /credits/track`, `GET /credits/reservations/{id}` | | Change a live subscription | [Versioning](/docs/subscriptions/versioning), [Amendments](/docs/subscriptions/amendments), [Updating a subscription](/docs/api-reference/v2/examples/updating-a-subscription) | `POST /subscriptions/{id}/changes/preview`, `POST /subscriptions/{id}/changes`, versions + `/publish` | | Feature gating | [Entitlements](/docs/entitlements/overview) | `GET /customers/{id}/entitlements`, `GET /subscriptions/{id}/entitlements` | | Invoices, credit notes, refunds | [Invoices](/docs/invoices/invoicing-customers), [Credit notes](/docs/invoices/credit-notes), [Refunds](/docs/invoices/refunds) | `/invoices`, `/credit-notes`, `/refunds` | | Self-serve checkout | [Checkout](/docs/hosted/checkout), [Embedded checkout](/docs/hosted/embedded-checkout) | `POST /checkout-sessions` | | Customer portal | [Customer portal](/docs/hosted/customer-portal) | `POST /customer-portal-sessions` | | React to billing events | [Webhooks](/docs/api-reference/v2/webhooks) | — | | Handle failures and retries | [Errors](/docs/api-reference/v2/errors), [Idempotency](/docs/api-reference/v2/idempotency) | — | | Revenue recognition | [Revenue recognition](/docs/revenue/recognition) | `/revenue-schedules` | | Use the SDK | [TypeScript SDK](/docs/api-reference/v2/sdks/typescript) | — | | Let an AI assistant operate billing | [MCP server](/docs/ai/mcp) | `https://api.alguna.io/mcp` | ## Dashboard-only today These exist in the product but have **no public API endpoints** in version `2026-04-01`. Do not generate API calls for them; direct the user to the dashboard. * Quotes and CPQ (create, send, e-sign) * Approval workflows configuration * Collections and dunning configuration * Automations ## Error handling Failed requests return `{ "status": , "detail": "" }`. Branch on the HTTP status, never on `detail` text. | Status | Retry? | Notes | | -------------------------- | ------------------------------------ | ------------------------------------------------------ | | `400`, `401`, `404`, `422` | No — fix the request | `422` is a validation failure on a well-formed request | | `409` | Yes, **same** `Idempotency-Key` | An earlier request with that key is still in flight | | `429` | Yes, after backoff | | | `500`, timeouts | Yes, with the same `Idempotency-Key` | | The TypeScript SDK raises `ValidationError` (400), `AuthenticationError` (401), `NotFoundError` (404), `RateLimitError` (429, with `retryAfter`) and `ApiError` (everything else), all carrying `statusCode`, `code` and `requestId`. Full detail: [Errors](/docs/api-reference/v2/errors). ## Rules for generated code * Always send both `Authorization` and `Alguna-Version`. * Use `snake_case` field names in bodies; `camelCase` only when parsing webhook payloads. * Never compute prices client-side and send a total. Send the events or the items; Alguna returns the charges. * Never put an API key in browser code. For browser purchase flows, mint a checkout session server-side and mount `@alguna/checkout-sdk`. * Use the sandbox (`api.sandbox.alguna.io`) with a sandbox key while developing; production keys do not work there and vice versa. * Before writing a call, confirm the operation exists in the [API reference](/docs/api-reference/v2/overview) for `2026-04-01`. Do not invent endpoints from naming patterns.