Credits Quick Start

This quick start gets a credit grant onto a customer’s subscription and shows you where it goes. A credit grant is a balance you allocate — monetary (in the subscription currency) or units (metric quantities) — that Alguna consumes automatically when the customer’s next invoice is priced. It takes a few minutes and needs only an active subscription. For the concepts behind it, read the Credits & Wallets Overview; for the full option set, Credit Grants. If you want customers to deposit money and pay invoices from it, that is a wallet, not a credit grant.

How it fits together

Grant — add credit to a customer’s subscription.
Invoice priced — the subscription’s upcoming invoice accrues charges.
Credit applied — eligible credit reduces the amount due, recorded as a pending ledger entry while the invoice is a draft.
Invoice issued — the consumption becomes final and whatever remains is collected. See Credit Consumption.

Step 1: Grant credit

Via API

curl -X POST https://api.alguna.io/subscriptions/sub_abc123/credits/grant \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.00",
    "credit_type": "monetary",
    "reason": "Welcome credit",
    "expires_at": "2026-12-31T00:00:00Z"
  }'

import os

import requests

response = requests.post(
    "https://api.alguna.io/subscriptions/sub_abc123/credits/grant",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={
        "amount": "25.00",
        "credit_type": "monetary",
        "reason": "Welcome credit",
        "expires_at": "2026-12-31T00:00:00Z",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json()["id"])

await alguna.subscriptions.createCreditGrant("sub_abc123", {
  amount: "25.00",
  credit_type: "monetary",
  reason: "Welcome credit",
  expires_at: "2026-12-31T00:00:00Z",
});

amount and reason are required; credit_type defaults to monetary. See Grant credits to a subscription.

Via dashboard

Open Customers, select the customer, and open the Credits card (or a subscription’s Credits & Entitlements section).
Click Add Credits and fill in:

Field	Description
Credit type	`Monetary` (subscription currency) or `Units` (metric quantities)
Amount	Value or quantity to grant
Expiration	Optional. Expired credit is removed and cannot be recovered
Reason	Internal note, e.g. “Welcome credit”
Applies to	Optional product/price restriction, evaluated only when credit is applied to an invoice. Does not affect realtime draws — see filters
Gate funding	Which billable metrics this grant funds for realtime `/check` and `/track` draws. Defaults to none — see gate funding

Click Add Credits.

Step 2: Watch it apply

Nothing else is needed. When the subscription’s next invoice is priced, eligible credit is drawn and the invoice shows the applied credit:

	Amount
Invoice subtotal	$150.00
Credit applied	−$25.00
Amount due	$125.00

If several grants could pay, they are drawn by priority, then expiring-first, then earliest expiry, then oldest. See consumption order. Monetary credit only applies to invoices in the same currency.

Step 3: Read the balance

curl https://api.alguna.io/subscriptions/sub_abc123/credits/balance \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

response = requests.get(
    "https://api.alguna.io/subscriptions/sub_abc123/credits/balance",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json()["balance"], response.json()["currency"])

const balance = await alguna.subscriptions.getCreditBalance("sub_abc123");

The endpoint reports the monetary balance; unit balances come back on /credits/check and /credits/track responses. In the dashboard, Customers → [Customer] → Credits shows the available balance by type, credit held against unissued invoices, credit expiring soon, and the ledger.

Common uses

Use	Grant	Suggested expiry
Welcome credit	`monetary`, e.g. `25.00`	90 days
Service compensation	`monetary`, reason with the incident reference	6 months
Referral reward	`monetary`	6 months
Prepaid usage package	`units`, e.g. `10000` API calls	12 months, or none

Recurring allowances (“1,000 calls included every month”) are not manual grants: put a credit_allocation entitlement on the plan and Alguna provisions an allocation grant each period. To have a package also authorise work in realtime before it happens, turn on gate funding for the grant and use the credit gate.

Ending credit early

There is no void action on an individual grant. Remaining credit is voided by a subscription version change whose transition policy says so — see Entitlements. Credit already applied to an issued invoice is never reversed.

Webhooks

Event	Fires when
`account.credits.granted`	A grant was created
`account.credits.balance_depleted`	The balance reached zero

See Webhooks. The credits_depleted automation trigger can email the customer or your team on the same condition.

Next steps

Credit Grants

Filters, gate funding, and grant origins.

Credit Consumption

Invoice-time consumption and the realtime gate.

Wallets

Prepaid money balances.

How Alguna Works

Where credits sit in the chain.

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Collections

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

How it fits together

Step 1: Grant credit

Via API

Via dashboard

Step 2: Watch it apply

Step 3: Read the balance

Common uses

Ending credit early

Webhooks

Next steps

Credit Grants

Credit Consumption

Wallets

How Alguna Works

​How it fits together

​Step 1: Grant credit

​Via API

​Via dashboard

​Step 2: Watch it apply

​Step 3: Read the balance

​Common uses

​Ending credit early

​Webhooks

​Next steps

Credit Grants

Credit Consumption

Wallets

How Alguna Works

How it fits together

Step 1: Grant credit

Via API

Via dashboard

Step 2: Watch it apply

Step 3: Read the balance

Common uses

Ending credit early

Webhooks

Next steps