List Voucher Grants

Returns voucher grants for one billing account in a project. Use this endpoint to show issued vouchers, remaining voucher balances, expiry state, and pagination.

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

Authentication

Authorization: Bearer <api-key>

Requires wallets read access.

Path Parameters

Field	Required	Description
project_id	Yes	Project that owns the account and voucher grants.

Query Parameters

Field	Required	Description
account_id	Yes	Billing account ID in the same project.
currency	No	Filter by voucher currency, for example USD.
expired	No	Filter by expiry state. Use false for active and not-yet-expired vouchers, or true for expired vouchers.
at	No	Unix timestamp used to evaluate expiry. Defaults to the current server time.
limit	No	Page size. Defaults to 20; maximum is 100.
offset	No	Page offset. Defaults to 0.

Example

curl 'http://127.0.0.1:8080/v1/projects/proj_gateway/voucher-grants?account_id=acct_org_001&currency=USD&expired=false&limit=20&offset=0' \
  -H 'Authorization: Bearer <api-key>'

Response

{
  "voucher_grants": [
    {
      "id": "vg_xxx",
      "tenant_id": "t_001",
      "project_id": "proj_gateway",
      "account_id": "acct_org_001",
      "currency": "USD",
      "original_amount": "25.00",
      "remaining_amount": "18.75",
      "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",
      "reconciled_usage_version": 42,
      "created_at": 1782720000,
      "updated_at": 1782800000
    }
  ],
  "total_count": 1,
  "limit": 20,
  "offset": 0
}

Notes

• status can be active, expired, or revoked. Expired status is evaluated against at for active grants with expires_at.
• The response returns persisted remaining balances plus runtime expiry status. Pending realtime usage may be reconciled into voucher grants asynchronously.
• Realtime wallet reads include active voucher availability in voucher_available.