Developers

This is the starting point for integrating Alguna from code. Alguna is one system for the whole quote-to-cash flow — pricing and packaging, subscriptions, usage metering, credits, invoicing, payment collection and revenue recognition — and everything the dashboard does for a sales-led deal is available to your application through the same API for a self-serve one. This page takes you from an API key to a metered, invoiced subscription, and links out to the deeper reference for each step. If you are new to the objects involved — customers, products, plans, subscriptions and their versions, metrics, invoices — read How Alguna works first. It is short, and every endpoint below maps onto it.

1. Get an API key

Sign in to the dashboard: app.alguna.io for production, app.sandbox.alguna.io for sandbox.
Go to Settings → Connections → Developers → API keys and create a key.
Store it as an environment variable. It is a server-side secret — never ship it to a browser or a mobile app.

export ALGUNA_API_KEY="..."

Sandbox and production are separate environments with separate keys and separate data. Build against sandbox first.

2. Base URL, authentication and versioning

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

Every request carries two headers:

Header	Value
`Authorization`	`Bearer $ALGUNA_API_KEY`
`Alguna-Version`	`2026-04-01` — the API version your integration is written against

Bodies are JSON in snake_case; amounts are decimal strings; timestamps are RFC 3339. Every response carries an X-Request-Id header — log it. Full details: API overview.

3. First request: create a customer

A customer is the account you bill. Give it your own identifier as an alias so you never need to store Alguna IDs: anywhere the API takes a customer, an alias works in place of the ID.

curl -X POST https://api.alguna.io/customers \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "currency": "USD",
    "aliases": ["acme-user-4821"],
    "contacts": [{ "email": "billing@acme.com", "is_primary": true }]
  }'

import os

import requests

BASE_URL = "https://api.alguna.io"
HEADERS = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{BASE_URL}/customers",
    headers=HEADERS,
    json={
        "name": "Acme Corp",
        "currency": "USD",
        "aliases": ["acme-user-4821"],
        "contacts": [{"email": "billing@acme.com", "is_primary": True}],
    },
    timeout=10,
)
response.raise_for_status()
customer = response.json()
print(customer["id"])

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

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

const customer = await alguna.customers.create({
  name: "Acme Corp",
  currency: "USD",
  aliases: ["acme-user-4821"],
  contacts: [{ email: "billing@acme.com", is_primary: true }],
});
console.log(customer.id);

name and currency are required. The response is the customer object, including its id. Reference: Create a customer, Look up a customer ID by alias.

Install the SDK with npm install @alguna/sdk. It is generated from the same OpenAPI spec as this reference, so every endpoint has a typed method and failed calls throw typed errors. See the TypeScript SDK.

4. Start a subscription

Pricing lives on products and is packaged into plans. The simplest way to subscribe a customer is to reference a plan; the subscription’s items are materialized from it. Subscriptions are created in draft — pass auto_activate: true to go live in one call, or call Activate a subscription later.

curl -X POST https://api.alguna.io/subscriptions \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-acme-user-4821" \
  -d '{
    "customer_id": "cust_abc123",
    "plan_id": "pln_032wMej82trlC5RulBsDJY",
    "auto_activate": true
  }'

response = requests.post(
    f"{BASE_URL}/subscriptions",
    headers={**HEADERS, "Idempotency-Key": "signup-acme-user-4821"},
    json={
        "customer_id": customer["id"],
        "plan_id": "pln_032wMej82trlC5RulBsDJY",
        "auto_activate": True,
    },
    timeout=10,
)
response.raise_for_status()
subscription = response.json()
print(subscription["id"], subscription["status"])

const subscription = await alguna.subscriptions.create(
  {
    customer_id: customer.id,
    plan_id: "pln_032wMej82trlC5RulBsDJY",
    auto_activate: true,
  },
  { idempotencyKey: "signup-acme-user-4821" },
);
console.log(subscription.id, subscription.status);

The Idempotency-Key makes the call safe to retry: a repeat with the same key returns the original subscription instead of creating a second one. See Idempotency. Once active, Alguna generates invoices on the schedule the plan defines and collects payment with the customer’s stored payment method. For inline pricing, per-customer overrides and bundles, see Creating a subscription; for upgrades and downgrades, Updating a subscription.

5. Meter usage

Usage-based prices read a billable metric: a named aggregation (count, count_unique, sum, average, min, max) over events with a given event_name, optionally filtered by event properties. Create the metric once, attach it to a metered product, then send events as usage happens.

Create a metric

curl -X POST https://api.alguna.io/metrics \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Requests",
    "event_name": "api_request",
    "aggregation": { "method": "count" }
  }'

response = requests.post(
    f"{BASE_URL}/metrics",
    headers=HEADERS,
    json={
        "name": "API Requests",
        "event_name": "api_request",
        "aggregation": {"method": "count"},
    },
    timeout=10,
)
response.raise_for_status()
metric = response.json()

const metric = await alguna.metrics.create({
  name: "API Requests",
  event_name: "api_request",
  aggregation: { method: "count" },
});

Send events

curl -X POST https://api.alguna.io/events \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "unique_id": "req_9f1c2e7a",
        "event_name": "api_request",
        "account": "acme-user-4821",
        "timestamp": "2026-04-01T10:30:00Z",
        "properties": { "endpoint": "/v1/analyze", "tokens": 1500 }
      }
    ]
  }'

import uuid
from datetime import datetime, timezone

response = requests.post(
    f"{BASE_URL}/events",
    headers=HEADERS,
    json={
        "events": [
            {
                "unique_id": str(uuid.uuid4()),
                "event_name": "api_request",
                "account": "acme-user-4821",
                "timestamp": datetime.now(timezone.utc).isoformat(),
                "properties": {"endpoint": "/v1/analyze", "tokens": 1500},
            }
        ]
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()
# A 200 does not mean every event was accepted — check `failed`.
if result["failed"]:
    print("rejected:", result["failed"])

const result = await alguna.events.ingest({
  events: [
    {
      unique_id: crypto.randomUUID(),
      event_name: "api_request",
      account: "acme-user-4821",
      timestamp: new Date().toISOString(),
      properties: { endpoint: "/v1/analyze", tokens: 1500 },
    },
  ],
});
if (result.failed.length > 0) console.warn("rejected:", result.failed);

Field	Required	Notes
`unique_id`	Yes	Idempotency key for the event, up to 72 characters. A resend with the same value is dropped, so retries are safe
`event_name`	Yes	Matches the metric’s `event_name`
`account`	Yes	Alguna customer ID, or an alias you set on the customer
`timestamp`	No	RFC 3339; defaults to now. Use the time the usage happened, not the time you sent it
`properties`	No	Up to 50 keys; used by metric filters and `sum`/`max`/… aggregations

Up to 100 events per request. The response lists which unique_ids were ingested and which failed. Batch and buffer on your side; send asynchronously. Full guide: Send usage events. Reference: Ingest billable events.

6. Gate features and credits

Two read paths tell your application what a customer is allowed to do:

Entitlements — feature flags and limits attached to the customer’s active subscription. GET /customers/{id}/entitlements returns them keyed by key with a type and value. See Entitlements and List active entitlements for a customer.
Credits — for prepaid or usage-gated products, POST /credits/check prices an intended action against the customer’s balance and can reserve the amount while the work runs; POST /credits/track settles it. See Credit consumption.

curl "https://api.alguna.io/customers/cust_abc123/entitlements" \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

7. Sell self-serve

For product-led signups you do not need to build a payment form. Mint a session server-side, hand the returned url to the browser:

Need	Endpoint	Page
Take a payment and start a plan, redirect or embedded	`POST /checkout-sessions`	Hosted checkout, Embedded checkout
Let a customer see invoices, change payment method, cancel	`POST /customer-portal-sessions`	Customer portal

Both sessions are short-lived and are created with your secret key; only the url (and, for embedded checkout, the session_token) is safe to expose. The end-to-end flow with trials and credits is in Launch self-serve.

8. Receive webhooks

Webhooks push events to your endpoint so you do not poll. Configure them under Settings → Connections → Developers → Webhooks: add your endpoint URL, choose events, and copy the signing secret. Events you will most likely subscribe to first:

Event	Fires when
`checkout.session.completed`	A checkout session’s payment succeeded
`subscription.activated`	A subscription became active
`subscription.canceled`	A subscription ended
`invoice.issued`	An invoice was finalized and sent
`invoice.paid`	An invoice was fully paid
`payment.updated`	A payment changed status — includes failures
`account.credits.balance_depleted`	A customer’s credit balance reached zero

Payloads are camelCase, wrapped as { "type", "timestamp", "data" }. Delivery is through Svix with signed requests; verify with the Svix library for your language rather than a hand-rolled check:

import { Webhook } from "svix";

const wh = new Webhook(process.env.ALGUNA_WEBHOOK_SECRET);
const event = wh.verify(rawBody, headers); // throws if the signature is invalid

import os

from svix.webhooks import Webhook

wh = Webhook(os.environ["ALGUNA_WEBHOOK_SECRET"])
event = wh.verify(raw_body, headers)  # raises on an invalid signature

Respond with a 2xx quickly and do the work asynchronously; failed deliveries are retried on a backoff. The full event catalogue, payloads and retry schedule are on the Webhooks page; the dashboard walkthrough is the Webhooks quick start.

9. Errors, retries and idempotency

Every error is { "status": <code>, "detail": "<message>" }. Branch on the status, never on the text.

Status	What to do
`400`, `422`	Fix the request; retrying unchanged fails again
`401`	Check the key and that it belongs to the environment you are calling
`404`	Check the ID — an object in the other environment reads as missing
`409`	A request with this idempotency key is still in flight; retry with the same key
`429`	Rate limited; back off and retry
`500`	Retry with the same idempotency key

The SDK raises ValidationError (400), AuthenticationError (401), NotFoundError (404), RateLimitError (429, with retryAfter) and ApiError for everything else, each carrying requestId. Details and retry guidance: Errors, Idempotency.

10. Test in sandbox

Sign in at app.sandbox.alguna.io and create a sandbox API key.
Point your integration at https://api.sandbox.alguna.io (with the SDK, pass baseUrl).
Connect your payment processor’s test mode and use its test cards at checkout.
Point webhooks at a tunnel (for example ngrok) or a request-capture service while you develop.

Run the whole lifecycle in sandbox — create, activate, meter, invoice, pay, cancel — before switching keys and base URL to production.

11. Use the API from an AI assistant

The same operations are exposed as tools on Alguna’s MCP server at https://api.alguna.io/mcp, with OAuth sign-in for clients that support it and an API key via mcp-remote for those that do not. Connect Claude, Cursor or ChatGPT to look up customers, create subscriptions or ingest events in natural language. See Model Context Protocol.

Limits

Limit	Value
Events per `POST /events` request	100
Properties per event	50
`unique_id` length	72 characters
`Idempotency-Key` length	255 printable ASCII characters, valid for 24 hours
Checkout session lifetime	5 minutes to 7 days (`expires_in_seconds`, default 24 hours)
Customer portal session lifetime	1 hour

Common patterns

Provision on signup

User signs up → POST /customers with your user ID as an alias
POST /subscriptions with plan_id and auto_activate: true (or send them through checkout)
Webhook subscription.activated → enable features; read entitlements as needed

Usage-based billing

POST /events as usage happens, batched, with a stable unique_id
End of period: Alguna aggregates the metric and issues the invoice → webhook invoice.issued
Payment collected → webhook invoice.paid

Prepaid credits

Grant credits (POST /subscriptions/{id}/credits/grant) → webhook account.credits.granted
Before expensive work, POST /credits/check; after it, POST /credits/track
Balance hits zero → webhook account.credits.balance_depleted → prompt an upgrade or top-up

Reference

API overview

Base URLs, headers, filtering, pagination.

TypeScript SDK

Typed client, errors and idempotency options.

Webhooks

Every event and payload.

Send usage

Event shape, batching and CSV import.

Metrics reference

Aggregations and filter operators.

Credits & wallets

Grants, consumption and wallets.

Subscriptions

Lifecycle, versions and amendments.

Model Context Protocol

Drive Alguna from an AI assistant.

AI & Infrastructure

Token-based and usage billing.

Self-Serve (PLG)

Checkout and upgrade flows.

Fintech & Payments

Transaction-based metering.

← Back to Quick Starts

See all quick start guides

Quick Starts

By Industry

By Motion

By Role

1. Get an API key

2. Base URL, authentication and versioning

3. First request: create a customer

4. Start a subscription

5. Meter usage

Create a metric

Send events

6. Gate features and credits

7. Sell self-serve

8. Receive webhooks

9. Errors, retries and idempotency

10. Test in sandbox

11. Use the API from an AI assistant

Limits

Common patterns

Reference

API overview

TypeScript SDK

Webhooks

Send usage

Metrics reference

Credits & wallets

Subscriptions

Model Context Protocol

AI & Infrastructure

Self-Serve (PLG)

Fintech & Payments

← Back to Quick Starts

​1. Get an API key

​2. Base URL, authentication and versioning

​3. First request: create a customer

​4. Start a subscription

​5. Meter usage

​Create a metric

​Send events

​6. Gate features and credits

​7. Sell self-serve

​8. Receive webhooks

​9. Errors, retries and idempotency

​10. Test in sandbox

​11. Use the API from an AI assistant

​Limits

​Common patterns

​Reference

API overview

TypeScript SDK

Webhooks

Send usage

Metrics reference

Credits & wallets

Subscriptions

Model Context Protocol

​Related quick starts

AI & Infrastructure

Self-Serve (PLG)

Fintech & Payments

← Back to Quick Starts

1. Get an API key

2. Base URL, authentication and versioning

3. First request: create a customer

4. Start a subscription

5. Meter usage

Create a metric

Send events

6. Gate features and credits

7. Sell self-serve

8. Receive webhooks

9. Errors, retries and idempotency

10. Test in sandbox

11. Use the API from an AI assistant

Limits

Common patterns

Reference

Related quick starts