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 Customer Account

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

{
  "name": "Acme Corp",
  "email": "billing@acme.com",
  "alias": "your-internal-id-123"
}

Response:

{
  "id": "acc_abc123",
  "name": "Acme Corp",
  "email": "billing@acme.com",
  "alias": "your-internal-id-123"
}

Store the Alguna id in your database. You’ll need it for granting credits, creating checkout sessions, and generating portal links. Alternatively, use alias to reference accounts by your internal ID.

Step 2: Grant Trial Credits

Give new users trial credits to try your product before subscribing. Endpoint: POST /accounts/{id}/credits/grants

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

This grants 50 units (e.g., API calls, runs, minutes) to the account.

Check Credit Balance

Endpoint: GET /accounts/{accountId}/credits/balance?type=units

{
  "accountId": "acc_abc123",
  "creditType": "units",
  "balance": "50"
}

Optional: Check Credit Availability

Before performing an action, verify the user has sufficient credits. Endpoint: GET /accounts/{accountId}/credits/availability?type=units&required=10

{
  "available": true,
  "balance": "50",
  "required": "10",
  "shortfall": "0"
}

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": "2025-03-03T17:06:07.473879Z",
  "data": {
    "accountId": "acc_abc123",
    "amount": "0",
    "type": "units"
  }
}

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

Step 4: Redirect to Hosted Checkout

When users are ready to subscribe, redirect them to Alguna’s hosted checkout.

Option A: Simple Redirect (No Code)

Redirect users directly to your checkout flow URL:

https://billing.yourcompany.com/checkout?flowId={flowId}&accountId={accountId}

Parameter	Description
`flowId`	Your checkout flow ID from the dashboard
`accountId`	The Alguna account ID
`pt`	Optional pass-through token for verification

Option B: Server-Side Session (More Control)

Create a checkout session via API for more flexibility. Endpoint: POST /customer-session/checkout

{
  "accountId": "acc_abc123",
  "accountEmail": "billing@acme.com",
  "currency": "USD",
  "successUrl": "https://yourapp.com/welcome",
  "passThroughToken": "your-internal-reference"
}

Response:

{
  "checkoutSessionId": "chk_xyz789",
  "url": "https://billing.yourcompany.com/checkout/session/..."
}

Redirect the user to the returned url.

Step 5: Handle Checkout Completion

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

Webhook Payload

{
  "type": "checkout.session.completed",
  "timestamp": "2025-03-03T17:06:07.473879Z",
  "data": {
    "id": "chk_xyz789",
    "accountId": "acc_abc123",
    "status": "completed",
    "amount": "49.00",
    "currency": "USD",
    "invoiceId": "inv_abc123",
    "paymentId": "pay_def456",
    "passThroughToken": "your-internal-reference"
  }
}

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. Events are processed within 15 minutes. Endpoint: POST /events

{
  "uniqueId": "evt_123456",
  "account": "acc_abc123",
  "eventName": "api_call",
  "timestamp": "2025-03-09T15:03:17Z",
  "properties": {
    "endpoint": "/v1/analyze",
    "tokens": 1500
  }
}

Field	Required	Description
`account`	Yes	Alguna account ID or your internal ID (alias)
`eventName`	Yes	The type of event (must match your billable metric)
`timestamp`	Yes	When the event occurred
`uniqueId`	No	For idempotency (prevents duplicate processing)
`properties`	No	Custom data for filtering and aggregation

For trial users, consider adding a property like "isTrial": true to distinguish trial usage from paid usage in your analytics.

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 Customer Portal

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

{
  "accountId": "acc_abc123",
  "planOverviewSettings": {
    "showSection": true,
    "allowSubscriptionCancel": true
  },
  "invoiceListSettings": {
    "showSection": true
  },
  "billingDetailsSettings": {
    "showSection": true
  }
}

Response:

{
  "sessionUrl": "https://billing.yourcompany.com/portal/..."
}

Redirect the user to sessionUrl when they click “Manage Billing” in your app.

Portal Configuration

Setting	Default	Description
`planOverviewSettings.showSection`	`true`	Show subscription details
`planOverviewSettings.allowSubscriptionCancel`	`true`	Allow self-service cancellation
`invoiceListSettings.showSection`	`true`	Show invoice history
`billingDetailsSettings.showSection`	`true`	Show billing info and payment methods

Use allowSubscriptionCancel: 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.created`	New subscription starts
`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 Customer Account

​Step 2: Grant Trial Credits

​Check Credit Balance

​Optional: Check Credit Availability

​Step 3: Handle Credit Depletion

​Configure Webhook

​Webhook Payload

​Step 4: Redirect to Hosted Checkout

​Option A: Simple Redirect (No Code)

​Option B: Server-Side Session (More Control)

​Step 5: Handle Checkout Completion

​Webhook Payload

​Step 6: Send Usage Events

​Usage Aggregation

​Step 7: Add 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 Customer Account

Step 2: Grant Trial Credits

Check Credit Balance

Optional: Check Credit Availability

Step 3: Handle Credit Depletion

Configure Webhook

Webhook Payload

Step 4: Redirect to Hosted Checkout

Option A: Simple Redirect (No Code)

Option B: Server-Side Session (More Control)

Step 5: Handle Checkout Completion

Webhook Payload

Step 6: Send Usage Events

Usage Aggregation

Step 7: Add Customer Portal

Portal Configuration

Complete Integration Flow

Key Webhooks

What You Don’t Need to Store

Testing

Next Steps