> ## 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.

# Guides

> Task-oriented guides for integrating Alguna: checkout, portal, subscriptions, usage metering, credits and webhooks.

These guides each take one integration task — accepting a payment, opening the customer portal, creating a subscription, metering usage, selling credits, receiving webhooks — from zero to a working implementation. Each one names the endpoints involved, shows the request and response shapes, and links to the concept and reference pages behind them. If you want the whole quote-to-revenue picture first, read [How Alguna works](https://alguna.com/docs/concepts/how-alguna-works.md); if you want the API basics in one place, start with the [Developer quick start](https://alguna.com/docs/quickstarts/developers.md).

***

## Guides

### Integrate from code

> **[SDKs and CLI](https://alguna.com/docs/guides/sdks-and-cli.md)**
>
> Pick a client, install it, connect, and make a first call in TypeScript, Python, Go, Rust or the terminal.

> **[MCP server](https://alguna.com/docs/ai/mcp.md)**
>
> Let an AI assistant do the same work in plain language, under your permissions.

### Payment and checkout

> **[Hosted checkout](https://alguna.com/docs/guides/hosted-checkout-integration.md)**
>
> Take a card or bank payment on a hosted page and create the subscription.

> **[Customer portal](https://alguna.com/docs/guides/customer-portal-integration.md)**
>
> Let customers see invoices, update payment methods and manage their plan.

### Subscriptions

> **[Create your first subscription](https://alguna.com/docs/guides/first-subscription.md)**
>
> Customer → product → subscription → activation.

> **[Subscription lifecycle](https://alguna.com/docs/guides/subscription-lifecycle.md)**
>
> Upgrades, downgrades, renewals and cancellations.

### Usage-based billing

> **[Usage metering](https://alguna.com/docs/guides/usage-metering-quickstart.md)**
>
> Define a metric, price it, and send usage events.

> **[Credits and prepaid](https://alguna.com/docs/guides/credits-quickstart.md)**
>
> Prepaid credits, wallets and real-time consumption.

### Events and self-serve

> **[Webhooks](https://alguna.com/docs/guides/webhooks-quickstart.md)**
>
> Receive notifications for billing events.

> **[Launch self-serve](https://alguna.com/docs/guides/launch-self-serve.md)**
>
> Trials, credits, checkout and portal in one flow.

***

## Before you start

### Get an API key

1. Sign in to the [dashboard](https://app.alguna.io) — or [sandbox](https://app.sandbox.alguna.io) while you build
2. Go to **Settings → Connections → Developers → [API keys](https://app.alguna.io/settings/connections/developers/api-keys)**
3. Create a key and keep it server-side

```bash theme={null}
export ALGUNA_API_KEY="your_api_key_here"
```

### Base URLs

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

### Authentication and versioning

Send the key as a Bearer token and pin the API version on every request:

```bash cURL 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"
```

```python Python theme={null}
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"]
```

```typescript TypeScript SDK theme={null}
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" });
```

Bodies are snake\_case JSON; webhook payloads are camelCase. Details in the [API overview](https://alguna.com/docs/api-reference/v2/overview.md).

***

## Common integration patterns

### Pattern 1: Checkout → subscription → invoice

The usual self-serve flow:

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant YourApp
    participant Alguna

    Customer->>YourApp: Select plan
    YourApp->>Alguna: POST /checkout-sessions
    Alguna-->>YourApp: session.url
    YourApp->>Customer: Redirect to checkout
    Customer->>Alguna: Complete payment
    Alguna->>Alguna: Create customer + subscription + paid invoice
    Alguna->>YourApp: Webhook: checkout.session.completed
    Alguna->>YourApp: Webhook: subscription.activated
    YourApp->>Customer: Grant access
```

### Pattern 2: API-first subscription

When your application already knows the customer and plan — sales-led deals, or self-serve with a stored payment method:

```mermaid theme={null}
sequenceDiagram
    participant YourApp
    participant Alguna

    YourApp->>Alguna: POST /customers
    Alguna-->>YourApp: customer.id
    YourApp->>Alguna: POST /subscriptions (plan_id, auto_activate)
    Alguna-->>YourApp: subscription (active)
    Alguna->>Alguna: Generate invoice on schedule
    Alguna->>YourApp: Webhook: invoice.issued
```

### Pattern 3: Usage-based billing

```mermaid theme={null}
sequenceDiagram
    participant YourApp
    participant Alguna

    loop As usage happens (batched)
        YourApp->>Alguna: POST /events
    end

    Note over Alguna: End of billing period
    Alguna->>Alguna: Aggregate metrics, price usage
    Alguna->>Alguna: Generate invoice
    Alguna->>YourApp: Webhook: invoice.issued
```

***

## Need help?

> **[API reference](https://alguna.com/docs/api-reference/v2/overview.md)**
>
> Every endpoint, generated from the OpenAPI spec.

> **[Support](mailto:support@alguna.io)**
>
> Include the `X-Request-Id` of any failed request.


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