Agent Integration Guide

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

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.

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.
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.
Bundle — a reusable group of prices.
Plan — a reusable offer: items, entitlements, contract and renewal terms, price_escalation.
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.
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.
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).
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.
Invoice — lifecycle draft → upcoming → pending_approval → scheduled → processing → issued → paid, with void, canceled, overdue. Corrections are credit notes and refunds.
Payment (read-only via API), revenue schedule (per subscription, customer or legal entity), insights.

Full explanation: How Alguna Works.

Which page to read for which task

Task	Read	Endpoints
Understand the model	How Alguna Works	—
Authenticate, version, paginate	API overview	—
Create a customer and first subscription	Create your first subscription, Creating a subscription	`POST /customers`, `POST /subscriptions`, `POST /subscriptions/{id}/activate`
Choose a pricing model	Pricing models (concepts), Pricing models reference (JSON shapes)	`POST /products`, prices inside subscription/plan `items`
Meter usage	Define metrics, Send usage	`POST /metrics`, `POST /events`
Prepaid credits and balances	Credits overview, Credit grants, Wallets	`/wallets`, `/wallet-grants`
Gate expensive work on balance	Credit consumption → Realtime gate	`POST /credits/check`, `POST /credits/track`, `GET /credits/reservations/{id}`
Change a live subscription	Versioning, Amendments, Updating a subscription	`POST /subscriptions/{id}/changes/preview`, `POST /subscriptions/{id}/changes`, versions + `/publish`
Feature gating	Entitlements	`GET /customers/{id}/entitlements`, `GET /subscriptions/{id}/entitlements`
Invoices, credit notes, refunds	Invoices, Credit notes, Refunds	`/invoices`, `/credit-notes`, `/refunds`
Self-serve checkout	Checkout, Embedded checkout	`POST /checkout-sessions`
Customer portal	Customer portal	`POST /customer-portal-sessions`
React to billing events	Webhooks	—
Handle failures and retries	Errors, Idempotency	—
Revenue recognition	Revenue recognition	`/revenue-schedules`
Use an SDK or the CLI	SDKs and CLI	—
Let an AI assistant operate billing	MCP server	`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 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.

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 for 2026-04-01. Do not invent endpoints from naming patterns.

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Collections

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

Agent Integration Guide

What Alguna is

Connection facts

First request

Object model

Which page to read for which task

Dashboard-only today

Error handling

Rules for generated code

​What Alguna is

​Connection facts

​First request

​Object model

​Which page to read for which task

​Dashboard-only today

​Error handling

​Rules for generated code

What Alguna is

Connection facts

First request

Object model

Which page to read for which task

Dashboard-only today

Error handling

Rules for generated code