Launch PLG in 15 Minutes

This guide walks you through launching a complete self-serve billing flow: free trials with credits, hosted checkout for upgrades, usage-based billing, and a customer portal for account management.

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: Get your API key from Settings → API Keys
Webhook Endpoint: Have a URL ready to receive webhooks
Checkout Flow: Create a checkout flow in Settings → Hosted Pages → Checkout Flows

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

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

Navigate to Settings → Webhooks
Add your endpoint URL
Subscribe to account.credits.balance_depleted

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. To render checkout inside your own page rather than redirecting, see Embedded Checkout.

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.

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 (e.g., unique users)
Sum	Sum a property value (e.g., total minutes)
Max	Maximum value in period

Configure aggregation in Billable Metrics in the dashboard.

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 are single-use and short-lived, so create one when the user clicks “Manage billing” rather than storing the link.

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 in Settings → 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

Use your Sandbox environment for testing
Create test accounts and grant credits
Deplete credits by sending test events
Complete a test checkout
Verify webhooks are received

Next Steps

Billable Metrics

Define how usage is measured and billed.

Customer Portal

Full portal configuration options.

Webhooks

Complete webhook reference.

API Reference

Full API documentation.

​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

API Reference

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