Credit Grants - Alguna Docs

A credit grant allocates credit to a customer’s subscription: a monetary amount in the subscription currency, or a quantity of metric units. Grants are consumed automatically when invoices are priced and, when opted in, by realtime /credits/check and /credits/track draws. Use this page to create grants through the API or dashboard, to control which charges a grant may pay for, and to read what is left. The rules for how credit is drawn are on Credit Consumption; the difference between grants and wallets is on the overview.

Create a grant

Via API

Credits are granted against a subscription. amount and reason are required; credit_type defaults to monetary; expires_at is optional. See Grant credits to a subscription.

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": "500.00",
    "credit_type": "monetary",
    "reason": "Q1 promotional credit",
    "expires_at": "2027-01-01T00: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": "500.00",
        "credit_type": "monetary",
        "reason": "Q1 promotional credit",
        "expires_at": "2027-01-01T00:00:00Z",
    },
    timeout=10,
)
response.raise_for_status()

grant = response.json()
print(grant["id"], grant["grant_type"], grant["amount"])

const grant = await alguna.subscriptions.createCreditGrant("sub_abc123", {
  amount: "500.00",
  credit_type: "monetary",
  reason: "Q1 promotional credit",
  expires_at: "2027-01-01T00:00:00Z",
});

Response:

{
  "id": "cg_abc123",
  "customer_id": "cust_01H2ABC",
  "subscription_id": "sub_abc123",
  "amount": "500.00",
  "grant_type": "api",
  "reason": "Q1 promotional credit",
  "expires_at": "2027-01-01T00:00:00Z",
  "created_at": "2026-04-01T10:00:00Z"
}

The grant is available immediately and fires the account.credits.granted webhook.

From the dashboard

Open Customers, select the customer, and open the Credits card — or the Credits & Entitlements section of one of their subscriptions.
Click Add Credits.
Fill in the grant:

Field	Description	Required
Credit type	`Monetary` or `Units`	Yes
Amount	Credit value or quantity	Yes
Reason	Why the credit was granted	Yes
Expiration	When unused credit lapses	No
Applies to	Product and price filters, invoice-time only (below)	No
Gate funding	Which metrics the grant funds at the realtime gate	No (defaults to `off`)

Click Add Credits.

Recurring allowances are not created here. They are provisioned by a credit_allocation entitlement on the plan or subscription, which creates an allocation grant each period.

Grant types

Monetary

{ "credit_type": "monetary", "amount": "1000.00", "reason": "Annual prepayment" }

Denominated in the subscription’s currency; never converted.
Applied while the invoice is priced, reducing amount_remaining; shown as applied credit on the invoice.
Reported by GET /subscriptions/{id}/credits/balance.

Units

{ "credit_type": "units", "amount": "50000", "reason": "50K API calls package" }

Denominated in metric units, not currency, and tracked separately from the monetary balance.
Cover metered lines at invoice time, and realtime draws when gate funding is on.
Reported on the balances of a /credits/check or /credits/track response.

A grant does not name a metric. Which metrics it may fund at the realtime gate is the separate gate-funding setting below.

A grant (or a subscription’s credit allocation) can be restricted to specific products or prices with include and exclude rules. In the dashboard this is the Applies to / Configure Credit Filters dialog on the credit entitlement.

These filters are invoice-time only. They decide which invoice lines the grant may pay for when an invoice is produced. They do not affect the realtime credit gate: /credits/check and /credits/track resolve a billable metric, not a product, so product and price filters are never evaluated there. What a grant funds at the gate is set separately — see Realtime gate funding below.The same applies to a grant made under a subscription. At invoice time the subscription scopes what the grant may pay for; for realtime draws it only records where the grant came from, and its credit is spendable against any metric its gate funding covers.

Realtime gate funding

Whether a grant pays for realtime /check and /track draws is a separate setting on the grant, expressed in billable metrics — the only thing the gate resolves. A product can sit above several metrics, which is why invoice-time filters cannot answer this question.

Setting	What the grant funds at the gate
`off`	Nothing. This is the default.
`all`	Any metric with an active credit consumption configuration, including ones configured later.
`chosen`	Only the billable metrics listed on the grant.

off is the default, including for every grant that already exists. Turning on the realtime gate covers nothing until you opt grants into it — deliberately, so credit bought for something else never starts funding the gate by surprise.

Naming a metric that has no active credit consumption configuration is allowed and returns a warning: the grant saves, and that part of the filter funds nothing until the configuration exists. Gate funding is a dashboard setting; the API grant endpoint creates grants with funding off.

Grant origin

grant_type records how a grant came about:

`grant_type`	Description
`allocation`	Provisioned by a subscription’s credit allocation entitlement
`manual`	Added by an operator in the dashboard
`api`	Created through the API
`rebalance`	Written by a version change that rebalanced an existing allocation

A grant has no status field. It is spendable from its creation until expires_at. A subscription version change can void an allocation’s remaining grant, depending on the transition policy set for that change — see Entitlements.

Expiration

expires_at is optional. Expired grants drop out of the balance from that moment; because the balance is evaluated at a point in time, a backdated charge can still draw on a grant that was live when the work happened.

Expired credit cannot be recovered. Set windows that match what you told the customer.

Consumption order

When several grants can pay for the same charge they are drawn in this order:

Priority — lowest number first
Expiring grants before non-expiring ones
Earliest expiry first
Oldest grant first

Priority is a dashboard setting on a subscription’s credit allocation, not an API field. Manual and API grants are priority 0. Set it on the allocation when allowance credit should be consumed ahead of purchased credit. Examples on Credit Consumption.

Read balances

Monetary balance via API

GET /subscriptions/{id}/credits/balance returns the customer’s monetary credit balance applicable to that subscription, evaluated at as_of (default: now). Expired grants are excluded. See Get the monetary credit 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()

balance = response.json()
print(balance["balance"], balance["currency"], balance["as_of"])

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

Response:

{
  "subscription_id": "sub_abc123",
  "credit_type": "monetary",
  "currency": "USD",
  "balance": "125.00",
  "as_of": "2026-04-01T00:00:00Z"
}

Unit balances

Unit balances are not reported by the endpoint above. Realtime unit availability comes back on the balances array of a /credits/check or /credits/track response, per metric — see Credit Consumption. A /credits/check with no reserve is a free way to read it.

Dashboard

Customers → [Customer] → Credits shows the balance by type, the grants behind it, and recent ledger activity.

Common scenarios

Service credit for an outage

Python

import os

import requests

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": "50.00",
        "credit_type": "monetary",
        "reason": "Service credit - 2026-03-15 outage",
    },
    timeout=10,
).raise_for_status()

Prepaid usage package

Python

import os

import requests

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": "100000",
        "credit_type": "units",
        "reason": "100K API calls package",
        "expires_at": "2027-01-01T00:00:00Z",
    },
    timeout=10,
).raise_for_status()

To let that package pay for realtime draws as well as invoice lines, turn on gate funding for the grant in the dashboard.

Next steps

Credit Consumption

How credit is drawn at invoice time and at the gate.

Entitlements

Recurring credit allocations on plans.

Wallets

Prepaid money balances.

How Alguna Works

Credits in the quote-to-cash chain.

​Create a grant

​Via API

​From the dashboard

​Grant types

​Monetary

​Units

​Product and price filters

​Realtime gate funding

​Grant origin

​Expiration

​Consumption order

​Read balances

​Monetary balance via API

​Unit balances

​Dashboard

​Common scenarios

​Service credit for an outage

​Prepaid usage package

​Next steps

Credit Consumption

Entitlements

Wallets

How Alguna Works

Create a grant

Via API

From the dashboard

Grant types

Monetary

Units

Product and price filters

Realtime gate funding

Grant origin

Expiration

Consumption order

Read balances

Monetary balance via API

Unit balances

Dashboard

Common scenarios

Service credit for an outage

Prepaid usage package

Next steps