> ## Documentation Index > Fetch the complete documentation index at: https://help-plum.xoxoday.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Vouchers API > Fetch a paginated list of vouchers from the Xoxoday catalog with optional filters and sorting. Pass `"exchangeRate": 1` to include FX rates in the response. Cache this response in your database and refresh periodically. **Real URL:** `POST https://stagingstores.xoxoday.com/chef/v1/oauth/api` | **Parameter** | **Type** | **Description** | | :-------------- | :-------------- | :------------------------------------------------------------------------------- | | limit | Int | Number of results to return per page (used for pagination). | | page | Int | Page number of results to fetch when using pagination. | | includeProducts | String | Comma-separated list of product IDs to explicitly include in the response. | | excludeProducts | String | Comma-separated list of product IDs to explicitly exclude from the response. | | sort | SortData | Sorting configuration (e.g., by price, name, popularity). | | sort.field | String | The field name to sort by (e.g., "name") | | sort.order | String | Sorting order → "ASC" for ascending or "DESC" for descending. | | filters | Array of Object | List of filters to apply. Each filter object should contain a key and **value**. | | filters.key | String | The filter key (e.g., `country`, `currency`, `product_category`). | | filters.value | String | The filter value corresponding to the key (e.g., `IN`, `USD`, `Electronics`). | ## Response Schema | **Path** | **Type** | **Description** | | :------------------------------------------------------ | :------------ | :------------------------------------------------------------------------ | | data | object | Root response object. | | data.getVouchers | object | Container for catalogue data. | | data.getVouchers.status | number | API execution status (`1` = success). | | data.getVouchers.data | array | List of voucher products. | | data.getVouchers.data\[].productId | number | Unique identifier for the voucher product. | | data.getVouchers.data\[].name | string | Product name. | | data.getVouchers.data\[].description | string (HTML) | Description (supports HTML content). | | data.getVouchers.data\[].orderQuantityLimit | number | Maximum quantity allowed per order. | | data.getVouchers.data\[].termsAndConditionsInstructions | string (HTML) | Terms & conditions; may contain HTML and links. | | data.getVouchers.data\[].brand | array | Brand metadata (may be empty). | | data.getVouchers.data\[].expiryAndValidity | string (HTML) | Voucher validity details. | | data.getVouchers.data\[].redemptionInstructions | string (HTML) | Instructions for redeeming the voucher. | | data.getVouchers.data\[].categories | string | Comma-separated list of product categories. | | data.getVouchers.data\[].lastUpdateDate | string | Last update timestamp. | | data.getVouchers.data\[].imageUrl | string | Product image URL. | | data.getVouchers.data\[].currencyCode | string | Currency code. | | data.getVouchers.data\[].currencyName | string | Currency name. | | data.getVouchers.data\[].countryName | string | Country where product is redeemable. | | data.getVouchers.data\[].countryCode | string | ISO country code. | | data.getVouchers.data\[].countries | array | List of redemption countries. | | data.getVouchers.data\[].countries\[].code | string | Country ISO code. | | data.getVouchers.data\[].countries\[].name | string | Country name. | | data.getVouchers.data\[].valueType | string | Denomination type (`fixed_denomination`, `open_value`). | | data.getVouchers.data\[].maxValue | number | Maximum value (for open value vouchers). | | data.getVouchers.data\[].minValue | number | Minimum value. | | data.getVouchers.data\[].valueDenominations | string | Comma-separated fixed denominations. | | data.getVouchers.data\[].tatInDays | string | Delivery turnaround time. | | data.getVouchers.data\[].usageType | string | `online`, `offline`, or `both`. | | data.getVouchers.data\[].deliveryType | string | `realtime` or `delayed`. | | data.getVouchers.data\[].fee | number | Additional fee applied. | | data.getVouchers.data\[].discount | number | Discount applied. | | data.getVouchers.data\[].exchangeRate | number | FX conversion rate used. | | data.getVouchers.data\[].isPhoneNumberMandatory | boolean | Whether phone number is required at checkout. | | data.getVouchers.data\[].variants | array / null | Product variants (if any). | | data.getVouchers.data\[].isRecommended | number | Recommendation flag (`0` or `1`). | | data.getVouchers.data\[].filterGroupCode | string | Filter group identifier. | | data.getVouchers.data\[].productMeta | string (JSON) | JSON structure defining dynamic checkout fields (e.g., email validation). | | data.getVouchers.data\[].loyaltyName | string / null | Loyalty program name. | | data.getVouchers.data\[].loyaltyConversion | number / null | Conversion factor for loyalty points. | | data.getVouchers.data\[].metaData | string / null | Additional metadata. | | data.getVouchers.data\[].showDiscountPercent | number | Whether discount percent should be displayed. | | data.getVouchers.data\[].productImages | array | Additional product images. | | data.getVouchers.data\[].parentProductId | number / null | Parent product reference. | | data.getVouchers.data\[].isDummyProduct | number | Indicates if item is dummy/test (`0` or `1`). | | data.getVouchers.data\[].redemptionFee | number | Redemption fee amount. | | data.getVouchers.data\[].redemptionFeeType | string | `percentage` or `fixed`. | | data.getVouchers.data\[].redemptionFeeBorneByUser | boolean | Whether user pays the redemption fee. | | data.getVouchers.data\[].redemptionFeeTax | number | Tax on redemption fee. | | data.getVouchers.data\[].is\_free | number | Whether voucher is free (`0` = paid, `1` = free). | ## Filter Reference Table | Key | Value Type | Description | | :----------- | :--------- | :------------------------------------------------ | | productName | String | Product names to be included | | country | String | Countries to be included | | price | String | Price range filters to be included | | minPrice | String | Minimum price of the products looked for | | maxPrice | String | Maximum price of the products looked for | | currencyCode | String | Currency codes to be included | | deliveryType | String | Delivery type to the voucher (realtime or delayed | ## Implementation Notes 1. To fetch exchangeRate in the GetVouchersAPI, pass "exchangeRate": 1 in the request body 2. To fetch the list of filters, use GetFiltersAPI 3. If the value type for a product is **"open\_value"**, please refer to the\*\*"minValue"**and the**"maxValue"\*\* parameters 4. The values passed in the "fee" and\*\*"discount"\*\* parameters are in percentage (%) 5. We recommend you cache the response from GetVouchersAPI in your database every time you sync our catalog 6. Use filters “minPrice” and “maxPrice” along with “currencyCode”, as this allows you to search prices with respect to a specific currency. If no currency is provided, the filter will not be applied. > Learn about [Error Handling](https://developers.xoxoday.com/v1.2/docs/error-handling-1), [Rate limiting](https://developers.xoxoday.com/v1.2/docs/rate-limiting) and [Best Practice](https://developers.xoxoday.com/v1.2/docs/concepts-1) . ## OpenAPI ````yaml specs/rewards-giftcard.yaml POST /getVouchers openapi: 3.0.3 info: title: Xoxoday Rewards API – Giftcard version: '1.2' description: > Giftcard API endpoints for browsing the catalog, placing orders, and reporting. All operations dispatch to `POST /v1/oauth/api` on the real server. OpenAPI does not allow multiple POST operations on the same path, so each operation uses a short virtual path suffix under the default server for playground differentiation. **Real URL for all operations:** `POST https://stagingstores.xoxoday.com/chef/v1/oauth/api` servers: - url: https://stagingstores.xoxoday.com/chef/v1/oauth/api description: Sandbox - url: https://accounts.xoxoday.com/chef/v1/oauth/api description: Production - url: https://canvas.xoxoday.com/chef/v1/oauth/api description: Testing security: - BearerAuth: [] tags: - name: Catalog - name: Orders - name: Reporting paths: /getVouchers: post: tags: - Catalog summary: Get Vouchers API description: > Fetch a paginated list of vouchers from the Xoxoday catalog with optional filters and sorting. Pass `"exchangeRate": 1` to include FX rates in the response. Cache this response in your database and refresh periodically. **Real URL:** `POST https://stagingstores.xoxoday.com/chef/v1/oauth/api` operationId: giftcardGetVouchers requestBody: required: true content: application/json: schema: type: object required: - query - tag - variables properties: query: type: string enum: - plumProAPI.mutation.getVouchers default: plumProAPI.mutation.getVouchers tag: type: string enum: - plumProAPI default: plumProAPI variables: type: object required: - data properties: data: type: object properties: limit: type: integer description: Number of results per page. example: 10 page: type: integer description: Page number to fetch. example: 1 includeProducts: type: string description: Comma-separated product IDs to include. example: '12345' excludeProducts: type: string description: Comma-separated product IDs to exclude. example: '54623' exchangeRate: type: integer description: >- Pass `1` to include FX exchange rates in the response. example: 1 sort: type: object properties: field: type: string description: Field to sort by. example: name order: type: string enum: - ASC - DESC example: ASC filters: type: array description: List of filter objects. items: type: object properties: key: type: string description: >- Filter key (e.g. `country`, `currency`, `minPrice`). value: type: string description: Filter value. example: query: plumProAPI.mutation.getVouchers tag: plumProAPI variables: data: limit: 10 page: 1 includeProducts: '12345' excludeProducts: '54623' exchangeRate: 1 sort: field: name order: ASC responses: '200': description: Voucher catalog returned successfully. content: application/json: schema: type: object properties: data: type: object properties: getVouchers: type: object properties: status: type: number data: type: array items: type: object properties: productId: type: number name: type: string description: type: string orderQuantityLimit: type: number imageUrl: type: string currencyCode: type: string countryName: type: string countryCode: type: string valueType: type: string maxValue: type: number minValue: type: number valueDenominations: type: string deliveryType: type: string usageType: type: string fee: type: number discount: type: number exchangeRate: type: number isPhoneNumberMandatory: type: boolean isRecommended: type: number is_free: type: number '401': $ref: '#/components/responses/Unauthorized' '502': $ref: '#/components/responses/BadGateway' components: responses: Unauthorized: description: Missing or invalid access token. content: application/json: schema: type: object properties: error: type: string example: Unauthorized BadGateway: description: Upstream service error. securitySchemes: BearerAuth: type: http scheme: bearer description: '`Authorization: Bearer `' ````