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

{
  "subject_type": "organization",
  "subject_id": "org_001",
  "currency": "USD",
  "amount": "25.00",
  "effective_from": 1782720000,
  "expires_at": 1785312000,
  "priority": 10,
  "source_type": "promotion",
  "source_id": "promo_summer_2026",
  "remark": "Summer promotion credit",
  "idempotency_key": "voucher:promo_summer_2026:acct_org_001"
}

Fields

Field	Required	Description
`account_id`	Conditionally	Billing account ID in the same project. Use this or `subject_type` plus `subject_id`.
`subject_type`	Conditionally	Subject type used to resolve the billing account when `account_id` is omitted.
`subject_id`	Conditionally	Subject ID used with `subject_type` to resolve the billing account.
`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.
`remark`	No	Grant reason, up to 500 Unicode characters, trimmed at both ends. Stored on the credit ledger entry and visible to readers.
`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 '{
    "subject_type": "organization",
    "subject_id": "org_001",
    "currency": "USD",
    "amount": "25.00",
    "source_type": "promotion",
    "source_id": "promo_summer_2026",
    "remark": "Summer promotion credit",
    "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",
    "remark": "Summer promotion credit",
    "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.

Empty remarks are omitted from responses. Retries with the same idempotency key preserve the original credit ledger remark. source_id remains the related business record identifier.