Rewards infrastructure,
ready to integrate.
Give your teams and customers instant access to eligible gift vouchers, wallet balances, and reliable order fulfillment through one clean API.
OpenAPI specification
The complete machine-readable contract for the Avirqo Public API. Import it into Postman, Insomnia, or your preferred API tooling to generate requests, validate responses, and build client SDKs.
Canonical definition: https://developers.avirqo.com/openapi.yaml
Authenticate
All API calls use a short-lived OAuth 2.0 bearer token. Your Avirqo administrator provides a Client ID and Client Secret. Keep both credentials on your server.
Use the client_credentials grant to receive a token valid for 15 minutes.
curl https://api.avirqo.com/v1/oauth/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=client_credentials&client_id=avq_live_...&client_secret=avq_secret_...'
List products
Products are filtered using the customer’s configured currencies, denominations, and account rules.
Optional query parameters: search matches a product name, brand, or public Avirqo product ID; country_code, currency_code, and page are also supported. A brand search may return multiple products.
curl 'https://api.avirqo.com/v1/products?search=amazon' \ -H 'Authorization: Bearer TOKEN'
Balance check
Balances are returned by currency and bucket. Amounts are decimal strings to avoid floating-point rounding errors.
Returns voucher balance, service-charge balance, and available balance.
Balance history
Use cursor pagination for reliable transaction history at any account size.
Filter by currency_code and type. Use cursor and limit for pagination.
Place an order
Every write request requires a unique Idempotency-Key. Retrying the same key returns the original order; changing the request with the same key returns a conflict.
Creates an order for exactly one voucher.
curl https://api.avirqo.com/v1/orders \
-H 'Authorization: Bearer TOKEN' \
-H 'Idempotency-Key: order-98412' \
-H 'Content-Type: application/json' \
-d '{"items":[{"product_id":123,"currency_code":"INR","denomination":1000}]}'Place a bulk order
Submit multiple product lines in one atomic request. Customer-level product, denomination, quantity, balance, and rate limits are enforced before fulfillment.
The configured customer limits apply. If one line fails, the request is rolled back and no balance is charged.
Retrieve vouchers
Retrieve voucher codes for any completed order owned by the authenticated customer. Every retrieval is recorded in the API audit log.
Treat this response as sensitive. Codes are encrypted at rest and returned only with the vouchers.read permission.
Errors & limits
Errors contain a stable machine-readable code and a human-readable message.
| Status | Meaning | What to do |
|---|---|---|
| 401 | Invalid or expired credentials | Request a new token. |
| 403 | Permission, customer, or IP policy rejected | Check the client configuration in Avirqo Settings. |
| 409 | Idempotency conflict | Reuse the original request key only for the same payload. |
| 422 | Validation, inventory, or balance failure | Correct the request or retry after resolving the business error. |
| 429 | Rate limit exceeded | Honor Retry-After and back off. |