Grant Voucher

Creates a project-scoped voucher grant for one billing account and currency. Voucher grants are funding buckets that are consumed before cash wallet balance while they are active.

POST /v1/projects/:project_id/voucher-grants

Authentication

Authorization: Bearer <api-key>
Content-Type: application/json

Requires wallets write access.

Path Parameters

Field	Required	Description
`project_id`	Yes	Project that owns the account, wallet, voucher grant, and ledger entries.

Request Body

{
  "account_id": "acct_org_001",
  "currency": "USD",
  "amount": "25.00",
  "effective_from": 1782720000,
  "expires_at": 1785312000,
  "priority": 10,
  "source_type": "promotion",
  "source_id": "promo_summer_2026",
  "idempotency_key": "voucher:promo_summer_2026:acct_org_001"
}

Fields

Field	Required	Description
`account_id`	Yes	Billing account ID in the same project.
`currency`	Yes	Voucher currency. It must match the wallet currency that later spends the voucher.
`amount`	Yes	Voucher amount. Must be greater than `0`. Use a JSON string for decimal precision.
`effective_from`	No	Unix timestamp when the voucher becomes active. Defaults to the current server time.
`expires_at`	No	Unix timestamp when the voucher expires. Omit for a non-expiring grant.
`priority`	No	Higher-priority active vouchers are consumed before lower-priority vouchers with the same expiry ordering.
`source_type`	No	Business source label, for example `promotion`, `manual_adjustment`, or `credit_pack`.
`source_id`	No	Business source ID for audit and reconciliation.
`idempotency_key`	No	Idempotency key for safely retrying the same voucher grant request.

Example

curl -X POST 'http://127.0.0.1:8080/v1/projects/proj_gateway/voucher-grants' \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "acct_org_001",
    "currency": "USD",
    "amount": "25.00",
    "source_type": "promotion",
    "source_id": "promo_summer_2026",
    "idempotency_key": "voucher:promo_summer_2026:acct_org_001"
  }'

Response

{
  "voucher_grant": {
    "id": "vg_xxx",
    "tenant_id": "t_001",
    "project_id": "proj_gateway",
    "account_id": "acct_org_001",
    "currency": "USD",
    "original_amount": "25.00",
    "remaining_amount": "25.00",
    "effective_from": 1782720000,
    "expires_at": 1785312000,
    "priority": 10,
    "status": "active",
    "source_type": "promotion",
    "source_id": "promo_summer_2026",
    "idempotency_key": "voucher:promo_summer_2026:acct_org_001",
    "created_at": 1782720000,
    "updated_at": 1782720000
  },
  "ledger_entry": {
    "id": "wle_xxx",
    "tenant_id": "t_001",
    "project_id": "proj_gateway",
    "account_id": "acct_org_001",
    "currency": "USD",
    "fund_type": "voucher",
    "fund_id": "vg_xxx",
    "direction": "credit",
    "amount": "25.00",
    "balance_after": "25.00",
    "source_type": "promotion",
    "source_id": "promo_summer_2026",
    "idempotency_key": "voucher_grant:voucher:promo_summer_2026:acct_org_001",
    "created_at": 1782720000
  }
}

Behavior

After the grant is created, Meterry:

persists the voucher grant and a voucher ledger credit entry in one transaction;
rebuilds the realtime voucher cache for the account and currency;
includes active voucher funds in realtime wallet availability;
consumes active voucher funds before cash balance for usage debit when voucher spending is allowed.

Notes

Voucher grants are project-scoped and account-scoped.
remaining_amount decreases as voucher funds are consumed.
Use List Voucher Grants to read issued vouchers and their remaining balances.