Launch PLG in 15 Minutes

Self-serve billing is the product-led half of quote-to-cash: the customer signs up, tries the product, pays by card, and manages their own account, without a sales or finance touch. This guide wires that flow end to end with the API — customer creation, trial credits, the depletion webhook, hosted checkout, usage events and the customer portal — and names the concept pages behind each step. If you also sell sales-led, the same objects carry both motions; see How Alguna works.

What You’ll Build

Phase	What Happens
Trial	User signs up → Create account → Grant trial credits
Upgrade	Credits depleted → Redirect to hosted checkout → User subscribes
Ongoing	Send usage events → Alguna bills automatically
Portal	User manages subscription, invoices, and payment methods

Prerequisites

Before starting:

API key — from Settings → Connections → Developers → API keys. See the Developer quick start for base URLs, headers and the SDK.
Webhook endpoint — a URL ready to receive webhooks; see the Webhooks quick start.
A plan to sell — a plan with the prices you want at checkout; see Plans. Create one in the dashboard or with Create a plan.

Step 1: Create the Customer

When a user signs up in your application, create a corresponding customer in Alguna. Endpoint: POST /customers

{
  "name": "Acme Corp",
  "currency": "USD",
  "aliases": ["your-internal-id-123"],
  "contacts": [
    { "email": "billing@acme.com", "is_primary": true }
  ]
}

name and currency are required. Put your own identifier in aliases so you can address the customer by it later. Reference: Create a customer. Response:

{
  "id": "cust_abc123",
  "name": "Acme Corp",
  "currency": "USD",
  "aliases": ["your-internal-id-123"],
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-01T10:00:00Z"
}

Store the Alguna id, or address the customer by the alias you set. Either works wherever a customer is referenced.

Step 2: Grant Trial Credits

Give new users credits to try your product before subscribing. Credits are granted against a subscription, so create the subscription first — a free or trial plan is enough. Endpoint: POST /subscriptions/{id}/credits/grant

{
  "amount": "50",
  "credit_type": "units",
  "reason": "Welcome credits"
}

amount and reason are required. Set credit_type to units for a usage allowance, or monetary for a currency balance. Add expires_at if the grant should lapse. Reference: Grant credits to a subscription; concepts in Credit grants.

Check the Balance

Endpoint: GET /subscriptions/{id}/credits/balance

{
  "subscription_id": "sub_abc123",
  "balance": "50",
  "credit_type": "units",
  "currency": "USD",
  "as_of": "2026-04-01T10:00:00Z"
}

Gate Work Before You Do It

To check whether a customer can afford an action, and hold the credit while the work runs, use the realtime gate: Endpoint: POST /credits/check

{
  "account": "cust_abc123",
  "event_name": "api_call",
  "events": [{ "properties": { "tokens": 1500 } }],
  "reserve": {},
  "ttl_seconds": 900
}

The response carries allowed, the priced charges per metric, and a reservation_id for the hold. When the work finishes, settle it with POST /credits/track, passing the reservation_id and close: true. See Credit Consumption.

Step 3: Handle Credit Depletion

When trial credits run out, Alguna sends a webhook so you can prompt the user to upgrade.

Configure Webhook

Go to Settings → Connections → Developers → Webhooks
Add your endpoint URL and copy the signing secret
Subscribe to account.credits.balance_depleted

Verify every delivery — see Webhooks.

Webhook Payload

{
  "type": "account.credits.balance_depleted",
  "timestamp": "2026-04-01T10:00:00Z",
  "data": {
    "accountId": "cust_abc123",
    "amount": "0",
    "type": "units"
  }
}

When you receive this webhook, redirect the user to your upgrade page or directly to hosted checkout.

Step 4: Send Users to Checkout

When a user is ready to subscribe, create a checkout session and redirect them to it. Endpoint: POST /checkout-sessions

{
  "plan_id": "plan_abc123",
  "customer_id": "cust_abc123",
  "success_url": "https://yourapp.com/welcome",
  "client_reference_id": "your-internal-reference",
  "expires_in_seconds": 86400
}

Response:

{
  "id": "chks_01H1VECT",
  "url": "https://acme.alguna.io/embed/checkout/elt_abc123",
  "checkout_intent": "payment",
  "currency": "USD",
  "client_reference_id": "your-internal-reference",
  "expires_at": "2026-04-02T10:00:00Z",
  "created_at": "2026-04-01T10:00:00Z"
}

Redirect the user to url. For a guest checkout, omit customer_id and pass a customer object instead; the customer is created when checkout completes. The response also carries status (created here; successful once paid) and a session_token. To render checkout inside your own page rather than redirecting, see Embedded Checkout. Reference: Create a checkout session.

Step 5: Handle Checkout Completion

When a user completes checkout, Alguna sends a webhook confirming the subscription.

Webhook Payload

{
  "type": "checkout.session.completed",
  "timestamp": "2026-04-01T10:05:00Z",
  "data": {
    "id": "chks_01H1VECT",
    "accountId": "cust_abc123",
    "status": "completed",
    "amount": "49.00",
    "currency": "USD",
    "invoiceId": "inv_abc123",
    "paymentId": "pay_def456",
    "subscriptionId": "sub_abc123",
    "clientReferenceId": "your-internal-reference"
  }
}

Webhook payloads are camelCase, unlike API request and response bodies. Match on clientReferenceId to find the record on your side. When you receive this:

Update the user’s status in your application
Grant access to paid features
Optionally send a welcome email

Step 6: Send Usage Events

Track usage by sending events to Alguna. Endpoint: POST /events

{
  "events": [
    {
      "unique_id": "evt_123456",
      "account": "cust_abc123",
      "event_name": "api_call",
      "timestamp": "2026-04-01T15:03:17Z",
      "properties": {
        "endpoint": "/analyze",
        "tokens": 1500
      }
    }
  ]
}

Field	Required	Description
`account`	Yes	Alguna customer ID, or an alias you set on the customer
`event_name`	Yes	The event type, matching the billable metric it should feed
`unique_id`	Yes	Idempotency key, up to 72 characters. A resend with the same value is dropped
`timestamp`	No	When the event occurred. Defaults to now
`properties`	No	Flat key/value data for filtering and aggregation, up to 50 keys

Send up to 100 events per request. The response lists which were ingested and which failed. Full details, including cURL, Python and SDK examples: Send usage events.

For trial users, add a property such as "is_trial": true so you can separate trial from paid usage in your metrics.

Usage Aggregation

Alguna can aggregate your events in different ways:

Aggregation	Use Case
`count`	Count every event (e.g., API calls)
`count_unique`	Count unique values of a property (e.g., unique users)
`sum`	Sum a property value (e.g., total minutes)
`average`	Average of a property value
`min` / `max`	Smallest or largest value in the period

Define metrics in Billable Metrics in the dashboard or with POST /metrics — see Create metrics.

Step 7: Add the Customer Portal

Let users manage their subscription, view invoices and update payment methods. Endpoint: POST /customer-portal-sessions

{
  "customer_id": "cust_abc123",
  "plan_overview_settings": {
    "show_section": true,
    "allow_subscription_cancel": true
  },
  "invoice_list_settings": {
    "show_section": true
  },
  "billing_details_settings": {
    "show_section": true
  }
}

Response:

{
  "id": "a8B3kLmQ",
  "url": "https://portal.alguna.io/hs/abc123",
  "customer_id": "cust_abc123",
  "expires_at": "2026-04-01T11:00:00Z",
  "created_at": "2026-04-01T10:00:00Z"
}

Sessions expire after 1 hour and are single-use, so create one when the user clicks “Manage billing” rather than storing the link. Reference: Create a customer portal session.

Portal Configuration

Each setting falls back to your organization’s default when omitted.

Setting	Description
`plan_overview_settings.show_section`	Show subscription details
`plan_overview_settings.allow_subscription_cancel`	Allow self-service cancellation
`plan_overview_settings.allow_self_serve_change`	Allow self-service plan changes
`invoice_list_settings.show_section`	Show invoice history
`billing_details_settings.show_section`	Show billing details and payment methods
`billing_details_settings.allow_payment_method_edit`	Allow the customer to change payment method

Set allow_subscription_cancel to false for enterprise customers who should contact sales to cancel.

Complete Integration Flow

┌─────────────────────────────────────────────────────────────────────┐
│                         YOUR APPLICATION                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  1. User signs up ──────► Create account in Alguna                  │
│                                    │                                │
│  2. Grant trial credits ◄──────────┘                                │
│           │                                                         │
│           ▼                                                         │
│  3. User uses product ──► Send usage events to Alguna               │
│           │                                                         │
│           ▼                                                         │
│  4. Credits depleted ◄─── Webhook: balance_depleted                 │
│           │                                                         │
│           ▼                                                         │
│  5. Redirect to checkout ──► Alguna hosted checkout                 │
│           │                                                         │
│           ▼                                                         │
│  6. User subscribes ◄──── Webhook: checkout.session.completed       │
│           │                                                         │
│           ▼                                                         │
│  7. Continue sending usage ──► Alguna bills automatically           │
│           │                                                         │
│           ▼                                                         │
│  8. "Manage Billing" ──► Redirect to customer portal                │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Key Webhooks

Subscribe to these webhooks under Settings → Connections → Developers → Webhooks:

Event	When It Fires
`checkout.session.completed`	User completes payment
`account.credits.balance_depleted`	Trial credits hit zero
`subscription.started`	The subscription period begins
`subscription.activated`	The subscription becomes active
`invoice.paid`	Invoice payment succeeds

What You Don’t Need to Store

Alguna handles these for you:

Subscription IDs and status
Product and plan details
Usage calculations and overages
Invoice generation and payment processing

You only need to store the Alguna account ID (or use your internal ID as an alias).

Testing

Build against sandbox: https://api.sandbox.alguna.io with a key from app.sandbox.alguna.io
Create test accounts and grant credits
Deplete credits by sending test events
Complete a test checkout with your processor’s test cards
Verify webhooks are received and signatures verify

Next Steps

Billable Metrics

Define how usage is measured and billed.

Customer Portal

Full portal configuration options.

Webhooks

Complete webhook reference.

Developer quick start

Auth, SDK, errors and sandbox in one page.

​What You’ll Build

​Prerequisites

​Step 1: Create the Customer

​Step 2: Grant Trial Credits

​Check the Balance

​Gate Work Before You Do It

​Step 3: Handle Credit Depletion

​Configure Webhook

​Webhook Payload

​Step 4: Send Users to Checkout

​Step 5: Handle Checkout Completion

​Webhook Payload

​Step 6: Send Usage Events

​Usage Aggregation

​Step 7: Add the Customer Portal

​Portal Configuration

​Complete Integration Flow

​Key Webhooks

​What You Don’t Need to Store

​Testing

​Next Steps

Billable Metrics

Customer Portal

Webhooks

Developer quick start

What You’ll Build

Prerequisites

Step 1: Create the Customer

Step 2: Grant Trial Credits

Check the Balance

Gate Work Before You Do It

Step 3: Handle Credit Depletion

Configure Webhook

Webhook Payload

Step 4: Send Users to Checkout

Step 5: Handle Checkout Completion

Webhook Payload

Step 6: Send Usage Events

Usage Aggregation

Step 7: Add the Customer Portal

Portal Configuration

Complete Integration Flow

Key Webhooks

What You Don’t Need to Store

Testing

Next Steps