Overview

The Alguna Public API is a JSON-over-HTTPS API for the whole quote-to-cash flow: customers, products and plans, subscriptions and their versions, usage events and metrics, credits and wallets, invoices, payments, refunds, tax and revenue schedules. Use it when you want your own systems to drive billing rather than the dashboard — provisioning customers on signup, metering usage, opening checkout, or reading revenue. How those objects relate is described in How Alguna works; the endpoint pages in this section are generated from the current OpenAPI spec.

Base URLs

Environment	Base URL	Dashboard
Production	`https://api.alguna.io`	app.alguna.io
Sandbox	`https://api.sandbox.alguna.io`	app.sandbox.alguna.io

Sandbox is a separate environment with its own data and its own API keys; a key issued in one environment is rejected by the other. All requests must be made over HTTPS.

Authentication

Every request carries an API key as a Bearer token:

Authorization: Bearer <API-KEY>

Create and manage keys in the dashboard under Settings → Connections → Developers → API keys. Keys are secrets — keep them server-side, never in a browser or mobile app. A missing or invalid key returns 401.

Versioning

The API is date-versioned. Send the Alguna-Version header on every request to pin the version your integration is written against; the current version is 2026-04-01. Upgrading is a deliberate change to that header, never a side effect of time passing.

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"

import os

import requests

response = requests.get(
    "https://api.alguna.io/customers",
    params={"limit": 20, "offset": 0, "sort": "name:asc"},
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
    },
    timeout=10,
)
response.raise_for_status()
customers = response.json()["data"]

import { Alguna } from "@alguna/sdk";

const alguna = new Alguna({
  apiKey: process.env.ALGUNA_API_KEY,
  apiVersion: "2026-04-01",
});

const { data: customers } = await alguna.customers.list({
  limit: 20,
  offset: 0,
  sort: "name:asc",
});

Use the version selector in the sidebar to browse the endpoints of a specific version. The TypeScript SDK sets the header for you from its apiVersion option.

Request and response format

Request and response bodies are JSON with snake_case field names (customer_id, plan_id). Webhook payloads are the exception — they are camelCase; see Webhooks.
Monetary amounts are decimal strings ("99.00"), never floats.
Timestamps are RFC 3339 (2026-04-01T10:00:00Z); dates are YYYY-MM-DD.
Send Content-Type: application/json on requests with a body.
Every response carries an X-Request-Id header — a UUID for that request. Log it and quote it when you contact support.

Filtering and sorting

List endpoints take filters as individual query parameters. Pass one value for an exact match, or comma-separated values for IN-style matching:

GET /invoices?limit=20&offset=0&sort=issue_date:desc&status=issued&customer_id=cust_abc123
GET /customers?limit=20&offset=0&sort=name:asc&tag_ids=tag_foo,tag_bar

Tag IDs can be looked up with List tags. The filter parameters each endpoint accepts are documented on its page. Sorting uses sort=<field>:<asc|desc>, for example name:asc.

Pagination

List endpoints require limit and offset, and most require sort. Send all three on every list request. Responses wrap the page in data and describe it in pagination:

{
  "data": [ ... ],
  "pagination": { "per_page": 20, "total_pages": 5 }
}

To walk a collection, increase offset by limit until offset / limit + 1 reaches total_pages.

Idempotency

Mutating endpoints (POST, PATCH, PUT, DELETE) accept an Idempotency-Key header so a retried request is applied at most once. POST /events is the exception: each event carries its own unique_id. See Idempotency.

Errors

Failed requests return a JSON body with the HTTP status and a human-readable detail:

{
  "status": 400,
  "detail": "Validation failed: name is required"
}

Status	Meaning
`400`	Bad request — malformed parameters
`401`	Unauthorized — missing or invalid API key
`404`	Not found — the resource does not exist in this environment
`409`	Conflict — a request with this idempotency key is still being processed
`422`	Unprocessable — well-formed, but violates a rule for the current state
`429`	Rate limited — back off and retry
`500`	Internal error — safe to retry with the same idempotency key

Branch on the status code, not on the text of detail. See Errors for typed SDK errors, request IDs and retry guidance.

Other ways in

TypeScript SDK — @alguna/sdk, one typed method per endpoint.
Webhooks — push notifications for subscription, invoice, payment, checkout and credit events.
MCP server — the same operations exposed as tools for AI assistants.
Developer quick start — first request to first invoice, end to end.

API Reference

Examples

SDKs

API Reference

Webhooks

Base URLs

Authentication

Versioning

Request and response format

Filtering and sorting

Idempotency

Errors

Other ways in

​Base URLs

​Authentication

​Versioning

​Request and response format

​Filtering and sorting

​Pagination

​Idempotency

​Errors

​Other ways in

Base URLs

Authentication

Versioning

Request and response format

Filtering and sorting

Pagination

Idempotency

Errors

Other ways in