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 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>`
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

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 the SDK	TypeScript SDK	—
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)
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`, `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.

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