Skip to main content
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

PriorityWhy It Matters
Clean APIFast integration, fewer bugs
Reliable webhooksKeep systems in sync
Usage meteringBill customers accurately
Sandbox environmentTest without affecting production
Good documentationLess 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

EnvironmentURL
Productionhttps://api.alguna.io
Sandboxhttps://api.sandbox.alguna.io

​
Rate Limits

Endpoint TypeLimit
Standard100 requests/second
Bulk operations10 requests/second
Usage ingestion1000 events/second

​
Key Integration Points

​
1. Customer Sync

Keep Alguna customers in sync with your user database:
Your SystemAlguna
User signs upCreate customer via API
User updates profileUpdate customer
User deletes accountCancel subscriptions, optionally delete
Endpoint: POST /customers

​
2. Usage Metering

Send usage events to bill customers accurately:
EventWhen to Send
API callAfter each billable API request
Storage usedDaily or hourly snapshot
Active usersDaily count at midnight
Compute timeAfter job completion
Endpoint: POST /events

​
3. Subscription Management

ActionEndpoint
Create subscriptionPOST /subscriptions
Get subscriptionGET /subscriptions/{id}
Activate subscriptionPOST /subscriptions/{id}/activate
Cancel subscriptionPOST /subscriptions/{id}/cancel

​
4. Entitlements Check

Check if a customer can access a feature:
CheckHow
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

EventWhen It Fires
subscription.activatedSubscription becomes active
subscription.canceledSubscription ended
invoice.issuedInvoice finalized
invoice.paidPayment successful
payment.createdPayment initiated
payment.updatedPayment status changed
account.credits.grantedCredits added to wallet
account.credits.balance_depletedCredit 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

AttemptDelay
1Immediate
25 minutes
330 minutes
42 hours
524 hours

​
Usage Metering

​
Sending Events

Send usage events as they occur: Endpoint: POST /events
FieldDescription
event_nameYour metric name (e.g., “api_call”)
customer_idAlguna customer ID
timestampISO 8601 timestamp
propertiesKey-value pairs for filtering and aggregation

​
Best Practices

PracticeWhy
Batch eventsSend in batches of 100-1000 for efficiency
Idempotency keysPrevent duplicate charges on retry
Buffer locallyQueue events locally, send async
Timestamp accuratelyUse event time, not send time

​
Deduplication

Include an idempotency_key to prevent duplicate processing:
ScenarioKey Strategy
API callsRequest ID
JobsJob ID + timestamp
Daily snapshotsCustomer ID + date

​
Sandbox Testing

​
Getting Started

  1. Log in to sandbox.alguna.io
  2. Get sandbox API keys at Settings → API Keys
  3. Use sandbox base URL: https://api.sandbox.alguna.io

​
Test Scenarios

ScenarioHow to Test
Successful paymentUse test card 4242 4242 4242 4242
Failed paymentUse test card 4000 0000 0000 0002
Subscription lifecycleCreate, activate, upgrade, cancel
Usage billingIngest events, generate invoice
WebhooksUse 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

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