> ## 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 the AI-native quote-to-revenue platform for B2B 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. Everything reads from one record per customer, the versioned agreement: an activated quote becomes the billing schedule, the subscription is the contract that was quoted, and invoices, payments, and revenue schedules read from it. Your integration works on that record.

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>` |
| API key format | `id.secret`, created in the dashboard under Settings → Connections → Developers → 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` and `POST /credits/track` are the exceptions: each event's `unique_id` identifies the work. A `POST /credits/check` hold (`reserve`) requires your own key. |
| 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" })` |
| Python, Go, Rust SDKs | `pip install alguna`, `go get github.com/alguna-io/alguna-go`, `cargo add alguna` |
| CLI | `npm install --global @alguna/cli` — `alguna login`, then `alguna <resource> <operation>` |
| 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](https://alguna.com/docs/concepts/how-alguna-works.md).

## Which page to read for which task

| Task | Read | Endpoints |
| - | - | - |
| Understand the model | [How Alguna Works](https://alguna.com/docs/concepts/how-alguna-works.md) | — |
| Authenticate, version, paginate | [API overview](https://alguna.com/docs/api-reference/v2/overview.md) | — |
| Create a customer and first subscription | [Create your first subscription](https://alguna.com/docs/guides/first-subscription.md), [Creating a subscription](https://alguna.com/docs/api-reference/v2/examples/creating-a-subscription.md) | `POST /customers`, `POST /subscriptions`, `POST /subscriptions/{id}/activate` |
| Choose a pricing model | [Pricing models](https://alguna.com/docs/pricing/pricing-models.md) (concepts), [Pricing models reference](https://alguna.com/docs/api-reference/v2/subscriptions/pricing-models.md) (JSON shapes) | `POST /products`, prices inside subscription/plan `items` |
| Meter usage | [Define metrics](https://alguna.com/docs/billable-metrics/define-metrics.md), [Send usage](https://alguna.com/docs/billable-metrics/send-usage.md) | `POST /metrics`, `POST /events` |
| Prepaid credits and balances | [Credits overview](https://alguna.com/docs/credits/overview.md), [Credit grants](https://alguna.com/docs/credits/credit-grants.md), [Wallets](https://alguna.com/docs/credits/wallets.md) | `/wallets`, `/wallet-grants` |
| Gate expensive work on balance | [Credit consumption → Realtime gate](https://alguna.com/docs/credits/credit-consumption.md) | `POST /credits/check`, `POST /credits/track`, `GET /credits/reservations/{id}` |
| Change a live subscription | [Versioning](https://alguna.com/docs/subscriptions/versioning.md), [Amendments](https://alguna.com/docs/subscriptions/amendments.md), [Updating a subscription](https://alguna.com/docs/api-reference/v2/examples/updating-a-subscription.md) | `POST /subscriptions/{id}/changes/preview`, `POST /subscriptions/{id}/changes`, versions + `/publish` |
| Feature gating | [Entitlements](https://alguna.com/docs/entitlements/overview.md) | `GET /customers/{id}/entitlements`, `GET /subscriptions/{id}/entitlements` |
| Invoices, credit notes, refunds | [Invoices](https://alguna.com/docs/invoices/invoicing-customers.md), [Credit notes](https://alguna.com/docs/invoices/credit-notes.md), [Refunds](https://alguna.com/docs/invoices/refunds.md) | `/invoices`, `/credit-notes`, `/refunds` |
| Self-serve checkout | [Checkout](https://alguna.com/docs/hosted/checkout.md), [Embedded checkout](https://alguna.com/docs/hosted/embedded-checkout.md) | `POST /checkout-sessions` |
| Customer portal | [Customer portal](https://alguna.com/docs/hosted/customer-portal.md) | `POST /customer-portal-sessions` |
| React to billing events | [Webhooks](https://alguna.com/docs/api-reference/v2/webhooks.md) | — |
| Handle failures and retries | [Errors](https://alguna.com/docs/api-reference/v2/errors.md), [Idempotency](https://alguna.com/docs/api-reference/v2/idempotency.md) | — |
| Revenue recognition | [Revenue recognition](https://alguna.com/docs/revenue/recognition.md) | `/revenue-schedules` |
| Use an SDK or the CLI | [SDKs and CLI](https://alguna.com/docs/api-reference/v2/sdks/overview.md) | — |
| Let an AI assistant operate billing | [MCP server](https://alguna.com/docs/ai/mcp.md) | `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). The [MCP server](https://alguna.com/docs/ai/mcp.md) can read quotes and draft new-business quotes; sending, signing and activation stay in the dashboard
* Approval workflows configuration
* Collections and dunning configuration
* Automations

## Error handling

Failed requests return `{ "status": <http status>, "detail": "<human-readable>" }`. Branch on the HTTP status, never on `detail` text.

| Status | Retry? | Notes |
| - | - | - |
| `400`, `401`, `403`, `404`, `422` | No — fix the request | `422` is a validation failure on a well-formed request |
| `409` with `Retry-After` | Yes, after `Retry-After` seconds, with the **same** `Idempotency-Key` | An earlier request with that key is still in flight |
| `429` | Yes, after backoff | Wait for `Retry-After` when the response has it |
| `502`, `503`, `504`, timeouts | Yes, with the same `Idempotency-Key` | |
| `500` | Not by the SDKs | An unexpected error. The request may have changed data, and a retry runs it again. Retry it over raw HTTP only when running it twice is safe, with the same `Idempotency-Key` |

The TypeScript SDK throws `ValidationError` (400), `UnprocessableEntityError` (422, extends `ValidationError`), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429), `InternalServerError` (any 5xx) and `ApiError` (any other status). When no response arrives it throws `ConnectionError`, or `TimeoutError` for a timed-out attempt, and `AbortError` when you abort the call. All extend `AlgunaError` and carry `statusCode`, `code` and `requestId`.

Every SDK retries a failed attempt twice before it throws: on `408`, `429`, `502`, `503` and `504`, on a `409` with `Retry-After`, and when no response arrived. It waits for `Retry-After` when the response has one, else it backs off exponentially. Every write carries an `Idempotency-Key`, yours or a generated one, that its retries reuse. `events.ingest`, `credits.track` and `credits.check` get no generated key: the events in the request body identify the work, so the SDK retries them without one. Do not wrap SDK calls in your own retry loop. Full detail: [Errors](https://alguna.com/docs/api-reference/v2/errors.md).

## 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](https://alguna.com/docs/api-reference/v2/overview.md) for `2026-04-01`. Do not invent endpoints from naming patterns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.