Concepts
This article will help you understand the key concepts you need to start working with the Xoxoday Rewards API quickly and confidently.
The following sections cover the essential elements of the API, so you can design, test, and deploy your integration without surprises.
Staging Environment
The Xoxoday staging environment is a free, fully-featured space for application development and testing. It supports all endpoints and functionality of the Rewards API, but with demo balances and a limited product catalog.
- Develop and test your application against staging first.
- Switch to production only when you’re ready to go live.
📘 Products & Denominations
The staging environment supports a limited set of products and denominations. Click here for the full list available in staging.
Catalog
The Xoxoday Rewards API provides access to a large collection of digital vouchers across multiple categories.
Refreshing the Catalog
To ensure you always have the latest product details, denominations, images, and terms & conditions, we recommend refreshing the catalog four times per day at:
- 12:00 AM
- 06:00 AM
- 12:00 PM
- 06:00 PM
All timings are in GMT+5:30 (India Time Zone).
Order Fulifment
Our product catalog includes two types of products based on delivery behavior:
- Real-Time Products
- Definition: Orders are processed and fulfilled instantly.
- Response Time: You’ll receive a success or failure response within 120 seconds.
- Use Case: Perfect for instant gratification and time-sensitive rewards.
- Delayed Gift Products
- Definition: Orders are placed into a pending state and fulfilled later.
- Fulfilment Time: Delivered within the estimated time provided in the API response (typically 3–10 working days).
- Use Case: Works well when a short delivery delay is acceptable.
PO Number (Purchase Order Number)
A PO Number (Purchase Order Number) is a unique reference ID that you, as a client, can generate and pass while placing an order through the Xoxoday API.
Purpose:
- Acts as an additional identifier for your orders, beyond the system-generated orderId.
- Prevents duplicate orders — if the same PO number is used again, the system will reject the request.
- Helps in reconciling orders easily during audits and reporting, since you can match transactions in your internal systems with the orders placed on Xoxoday.
Example Use Case:
If your system sends the same order request twice due to a retry or timeout, the PO number ensures that only one order is created.
Recommendation:
Always pass a unique PO number from your system when placing orders.
Note: Use the deliveryType field in the GetVouchers API response to determine if a product is realtime or delayed.
Recommended Practices
Follow these guidelines to ensure smooth API consumption and integration:
-
Catalog Refresh
Sync your catalog four times daily (12:00 AM, 06:00 AM, 12:00 PM, 06:00 PM) to always have the latest products and data. -
Use of PO Number
Implement the PO number field to avoid placing duplicate orders. -
API Timeout Handling
Allow up to 120 seconds for API responses, especially for real-time gift cards, due to possible vendor system delays. -
Error Code Handling
Leverage the wide range of error codes provided in API responses to improve error handling and provide clear user feedback.
Authentication Overview
All requests to the Reward APIs and Reward Links APIs must be authenticated.
Note: Xoxoday uses the standard OAuth 2.0 protocol and a RESTful Rewards API to enable seamless voucher integrations.
The overall authentication process remains the same across Reward APIs, Reward Links APIs, Storefront Integration APIs, and Reward Points APIs. The only difference lies in how tokens are generated and the validity period of these tokens.
- Reward APIs and Reward Links APIs → Same process for token generation and validity.
- Storefront Integration APIs and Reward Points APIs → Follow a different, but common, process for token generation and validity.
For complete details, refer to the dedicated authentication documentation for each API type:
Updated 9 days ago