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.
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":"AVQ-PROD-AMZ-IN-00123","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.
Send Rewards
Place one consolidated voucher order and send the recipient a secure download invitation. The recipient email and optional personal message are stored with the order; voucher codes are never included in the API response or email.
Creates the order and sends a secure, one-time voucher download invitation to the recipient after fulfillment.
Retrieve vouchers
Retrieve voucher codes for any completed order owned by the authenticated customer. Use the public order number in AVQ-SEND-YYYY-NNNNNN format. 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. The standard limits below are measured per minute. Your administrator may configure a lower global or customer limit; the effective limit is always the most restrictive one.
Standard API limits
| API | Method | Standard limit |
|---|---|---|
| Authenticate | POST /oauth/token | 5 requests/minute |
| List products | GET /products | 30 requests/minute |
| Balance check | GET /balances | 30 requests/minute |
| Balance history | GET /balance-history | 30 requests/minute |
| Place order | POST /orders | 30 requests/minute |
| Bulk orders | POST /bulk-orders | 30 requests/minute |
| Send Rewards | POST /send-rewards | 30 requests/minute |
| Retrieve vouchers | GET /orders/{order_number}/vouchers | 30 requests/minute |
When a limit is exceeded, the API returns 429 and a Retry-After header. Back off for the indicated duration before retrying.
HTTP errors
| 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. |
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