> ## 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-cash picture first, read [How Alguna works](/docs/concepts/how-alguna-works); if you want the API basics in one place, start with the [Developer quick start](/docs/quickstarts/developers).

***

## Guides

### Payment and checkout

<CardGroup cols={2}>
  <Card title="Hosted checkout" icon="credit-card" href="/docs/guides/hosted-checkout-integration">
    Take a card or bank payment on a hosted page and create the subscription.
  </Card>

  <Card title="Customer portal" icon="user" href="/docs/guides/customer-portal-integration">
    Let customers see invoices, update payment methods and manage their plan.
  </Card>
</CardGroup>

### Subscriptions

<CardGroup cols={2}>
  <Card title="Create your first subscription" icon="repeat" href="/docs/guides/first-subscription">
    Customer → product → subscription → activation.
  </Card>

  <Card title="Subscription lifecycle" icon="arrows-spin" href="/docs/guides/subscription-lifecycle">
    Upgrades, downgrades, renewals and cancellations.
  </Card>
</CardGroup>

### Usage-based billing

<CardGroup cols={2}>
  <Card title="Usage metering" icon="chart-line" href="/docs/guides/usage-metering-quickstart">
    Define a metric, price it, and send usage events.
  </Card>

  <Card title="Credits and prepaid" icon="coins" href="/docs/guides/credits-quickstart">
    Prepaid credits, wallets and real-time consumption.
  </Card>
</CardGroup>

### Events and self-serve

<CardGroup cols={2}>
  <Card title="Webhooks" icon="bell" href="/docs/guides/webhooks-quickstart">
    Receive notifications for billing events.
  </Card>

  <Card title="Launch self-serve" icon="rocket" href="/docs/guides/launch-self-serve">
    Trials, credits, checkout and portal in one flow.
  </Card>
</CardGroup>

***

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

<CodeGroup>
  ```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" });
  ```
</CodeGroup>

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

***

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

<CardGroup cols={2}>
  <Card title="API reference" icon="book" href="/docs/api-reference/v2/overview">
    Every endpoint, generated from the OpenAPI spec.
  </Card>

  <Card title="Support" icon="headset" href="mailto:support@alguna.io">
    Include the `X-Request-Id` of any failed request.
  </Card>
</CardGroup>