Developers - Alguna Docs

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

Navigate to Settings → Webhooks
Add your endpoint URL
Select events to receive
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:

Get the X-Webhook-Signature header
Compute HMAC-SHA256 of the raw body using your signing secret
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

Log in to sandbox.alguna.io
Get sandbox API keys at Settings → API Keys
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

Customer signs up in your app
Your app creates Alguna customer
Your app creates subscription
Webhook: subscription.activated
Your app enables features for customer

Usage-Based Billing

Customer uses your product
Your app sends usage events to Alguna
End of billing period
Alguna aggregates usage, generates invoice
Webhook: invoice.issued
Payment collected
Webhook: invoice.paid

Credit System

Customer buys credits
Webhook: account.credits.granted
Customer uses product
Your app decrements credits (or Alguna tracks usage)
Credits low: webhook or alert
Webhook: account.credits.balance_depleted

Key Resources

Billable Metrics

Define what usage to track.

Send Usage

Ingesting usage events.

Credits & Wallets

Pre-paid credit systems.

Subscriptions

Managing subscription lifecycle.

API Reference

API Overview

Authentication, rate limits, errors.

Ingest Events

Send usage events.

Webhooks

Event payloads and setup.

Customers API

Create and manage customers.

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

​What Developers Care About

​API Basics

​Authentication

​Base URLs

​Rate Limits

​Key Integration Points

​1. Customer Sync

​2. Usage Metering

​3. Subscription Management

​4. Entitlements Check

​Webhooks

​Setup

​Webhook Events

​Verifying Signatures

​Retry Policy

​Usage Metering

​Sending Events

​Best Practices

​Deduplication

​Sandbox Testing

​Getting Started

​Test Scenarios

​Common Patterns

​Provisioning on Subscription

​Usage-Based Billing

​Credit System

​Key Resources

Billable Metrics

Send Usage

Credits & Wallets

Subscriptions

​API Reference

API Overview

Ingest Events

Webhooks

Customers API

​Related Quick Starts

AI & Infrastructure

Self-Serve (PLG)

Fintech & Payments

← Back to Quick Starts

What Developers Care About

API Basics

Authentication

Base URLs

Rate Limits

Key Integration Points

1. Customer Sync

2. Usage Metering

3. Subscription Management

4. Entitlements Check

Webhooks

Setup

Webhook Events

Verifying Signatures

Retry Policy

Usage Metering

Sending Events

Best Practices

Deduplication

Sandbox Testing

Getting Started

Test Scenarios

Common Patterns

Provisioning on Subscription

Usage-Based Billing

Credit System

Key Resources

API Reference

Related Quick Starts