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

# Developers

> APIs, webhooks, SDKs, and usage metering integration

Developers need clean APIs, reliable webhooks, and easy-to-integrate metering. This guide covers the technical integration points that matter most.

***

## What Developers Care About

| Priority                | Why It Matters                    |
| ----------------------- | --------------------------------- |
| **Clean API**           | Fast integration, fewer bugs      |
| **Reliable webhooks**   | Keep systems in sync              |
| **Usage metering**      | Bill customers accurately         |
| **Sandbox environment** | Test without affecting production |
| **Good documentation**  | Less time debugging               |

***

## API Basics

### Authentication

All API requests require a Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

Get your API key at **Settings** → **API Keys**

### Base URLs

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

### Rate Limits

| Endpoint Type   | Limit               |
| --------------- | ------------------- |
| Standard        | 100 requests/second |
| Bulk operations | 10 requests/second  |
| Usage ingestion | 1000 events/second  |

***

## Key Integration Points

### 1. Customer Sync

Keep Alguna customers in sync with your user database:

| Your System          | Alguna                                  |
| -------------------- | --------------------------------------- |
| User signs up        | Create customer via API                 |
| User updates profile | Update customer                         |
| User deletes account | Cancel subscriptions, optionally delete |

**Endpoint**: `POST /customers`

### 2. Usage Metering

Send usage events to bill customers accurately:

| Event        | When to Send                    |
| ------------ | ------------------------------- |
| API call     | After each billable API request |
| Storage used | Daily or hourly snapshot        |
| Active users | Daily count at midnight         |
| Compute time | After job completion            |

**Endpoint**: `POST /events`

### 3. Subscription Management

| Action                | Endpoint                            |
| --------------------- | ----------------------------------- |
| Create subscription   | `POST /subscriptions`               |
| Get subscription      | `GET /subscriptions/{id}`           |
| Activate subscription | `POST /subscriptions/{id}/activate` |
| Cancel subscription   | `POST /subscriptions/{id}/cancel`   |

### 4. Entitlements Check

Check if a customer can access a feature:

| Check                | How                                               |
| -------------------- | ------------------------------------------------- |
| Active subscription? | `GET /subscriptions?accountId={id}&status=active` |
| On specific plan?    | Check `planId` in subscription response           |
| Within usage limits? | Compare current usage to plan limits              |

***

## Webhooks

Alguna sends webhooks to notify your systems of billing events.

### Setup

1. Navigate to **Settings** → **Webhooks**
2. Add your endpoint URL
3. Select events to receive
4. Copy the signing secret

### Webhook Events

| Event                              | When It Fires               |
| ---------------------------------- | --------------------------- |
| `subscription.activated`           | Subscription becomes active |
| `subscription.canceled`            | Subscription ended          |
| `invoice.issued`                   | Invoice finalized           |
| `invoice.paid`                     | Payment successful          |
| `payment.created`                  | Payment initiated           |
| `payment.updated`                  | Payment status changed      |
| `account.credits.granted`          | Credits added to wallet     |
| `account.credits.balance_depleted` | Credit balance exhausted    |

### Verifying Signatures

Always verify webhook signatures to ensure authenticity:

1. Get the `X-Webhook-Signature` header
2. Compute HMAC-SHA256 of the raw body using your signing secret
3. Compare signatures (use constant-time comparison)

### Retry Policy

| Attempt | Delay      |
| ------- | ---------- |
| 1       | Immediate  |
| 2       | 5 minutes  |
| 3       | 30 minutes |
| 4       | 2 hours    |
| 5       | 24 hours   |

***

## Usage Metering

### Sending Events

Send usage events as they occur:

**Endpoint**: `POST /events`

| Field         | Description                                   |
| ------------- | --------------------------------------------- |
| `event_name`  | Your metric name (e.g., "api\_call")          |
| `customer_id` | Alguna customer ID                            |
| `timestamp`   | ISO 8601 timestamp                            |
| `properties`  | Key-value pairs for filtering and aggregation |

### Best Practices

| Practice                 | Why                                        |
| ------------------------ | ------------------------------------------ |
| **Batch events**         | Send in batches of 100-1000 for efficiency |
| **Idempotency keys**     | Prevent duplicate charges on retry         |
| **Buffer locally**       | Queue events locally, send async           |
| **Timestamp accurately** | Use event time, not send time              |

### Deduplication

Include an `idempotency_key` to prevent duplicate processing:

| Scenario        | Key Strategy       |
| --------------- | ------------------ |
| API calls       | Request ID         |
| Jobs            | Job ID + timestamp |
| Daily snapshots | Customer ID + date |

***

## Sandbox Testing

### Getting Started

1. Log in to [sandbox.alguna.io](https://app.sandbox.alguna.io)
2. Get sandbox API keys at **Settings** → **API Keys**
3. Use sandbox base URL: `https://api.sandbox.alguna.io`

### Test Scenarios

| Scenario               | How to Test                         |
| ---------------------- | ----------------------------------- |
| Successful payment     | Use test card `4242 4242 4242 4242` |
| Failed payment         | Use test card `4000 0000 0000 0002` |
| Subscription lifecycle | Create, activate, upgrade, cancel   |
| Usage billing          | Ingest events, generate invoice     |
| Webhooks               | Use webhook.site or ngrok           |

***

## Common Patterns

### Provisioning on Subscription

```
1. Customer signs up in your app
2. Your app creates Alguna customer
3. Your app creates subscription
4. Webhook: subscription.activated
5. Your app enables features for customer
```

### Usage-Based Billing

```
1. Customer uses your product
2. Your app sends usage events to Alguna
3. End of billing period
4. Alguna aggregates usage, generates invoice
5. Webhook: invoice.issued
6. Payment collected
7. Webhook: invoice.paid
```

### Credit System

```
1. Customer buys credits
2. Webhook: account.credits.granted
3. Customer uses product
4. Your app decrements credits (or Alguna tracks usage)
5. Credits low: webhook or alert
6. Webhook: account.credits.balance_depleted
```

***

## Key Resources

<CardGroup cols={2}>
  <Card title="Billable Metrics" icon="chart-line" href="/billable-metrics/define-metrics">
    Define what usage to track.
  </Card>

  <Card title="Send Usage" icon="gauge" href="/billable-metrics/send-usage">
    Ingesting usage events.
  </Card>

  <Card title="Credits & Wallets" icon="wallet" href="/credits/overview">
    Pre-paid credit systems.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/subscriptions/overview-subscriptions">
    Managing subscription lifecycle.
  </Card>
</CardGroup>

***

## API Reference

<CardGroup cols={2}>
  <Card title="API Overview" icon="book" href="/api-reference/overview">
    Authentication, rate limits, errors.
  </Card>

  <Card title="Ingest Events" icon="upload" href="/api-reference/events/ingest">
    Send usage events.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Event payloads and setup.
  </Card>

  <Card title="Customers API" icon="users" href="/api-reference/customers/create">
    Create and manage customers.
  </Card>
</CardGroup>

***

## Related Quick Starts

<CardGroup cols={3}>
  <Card title="AI & Infrastructure" icon="microchip" href="/quickstarts/ai">
    Token-based and usage billing.
  </Card>

  <Card title="Self-Serve (PLG)" icon="cart-shopping" href="/quickstarts/self-serve">
    Checkout and upgrade flows.
  </Card>

  <Card title="Fintech & Payments" icon="credit-card" href="/quickstarts/fintech">
    Transaction-based metering.
  </Card>
</CardGroup>

<Card title="← Back to Quick Starts" icon="arrow-left" href="/quickstarts/overview">
  See all quick start guides
</Card>