> ## 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 Merchandise API > Fetch a paginated list of available merchandise products from the catalog. Must pass `"categoryType": "merchandise"` in the request body. **Real URL:** `POST https://accounts.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. To fetch the merchandise catalog, pass "**category\_type": "merchandise" in the request body. If this parameter is not passed, the API will return the default Gift Card** catalog. 5. The values passed in the "fee" and\*\*"discount"\*\* parameters are in percentage (%) 6. We recommend you cache the response from GetVouchersAPI in your database every time you sync our catalog 7. Use filters “minPrice” and “maxPrice” along with “currencyCode”, as this allows you to search prices with respect to a specific currency. If "currencyCode" code is not added, the filter will be applicable for all currencies. > 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-merchandise.yaml POST /getMerchandise openapi: 3.0.3 info: title: Xoxoday Rewards API – Merchandise version: '1.2' description: > Merchandise API endpoints for browsing the catalog, placing orders, and reporting. All operations dispatch to `POST /v1/oauth/api`. Virtual path suffixes are used for playground differentiation since OpenAPI does not allow multiple POST operations on the same path. **Host split:** - `getFilters`, `getBalance`, `paymentHistory` → `stagingstores.xoxoday.com` - `getMerchandise`, `placeOrder`, `getOrderDetails`, `getOrderHistory` → `accounts.xoxoday.com` **Notable differences from other categories:** - Place Order: `productId` is a string, shipping fields are flat inside `data` - Get Order Details: `variables` fields are flat (no `data` wrapper) 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: /getMerchandise: post: tags: - Catalog summary: Get Merchandise API description: > Fetch a paginated list of available merchandise products from the catalog. Must pass `"categoryType": "merchandise"` in the request body. **Real URL:** `POST https://accounts.xoxoday.com/chef/v1/oauth/api` operationId: merchandiseGetCatalog 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 required: - categoryType properties: categoryType: type: string enum: - merchandise default: merchandise description: Must be `"merchandise"` for this endpoint. limit: type: integer example: 10 page: type: integer example: 1 includeProducts: type: string description: Comma-separated product IDs to include. example: '23353' excludeProducts: type: string description: Comma-separated product IDs to exclude. example: '1133' exchangeRate: type: integer description: Pass `1` to include FX exchange rates. example: 1 sort: type: object properties: field: type: string example: name order: type: string enum: - ASC - DESC example: ASC filters: type: array items: type: object properties: key: type: string value: type: string example: query: plumProAPI.mutation.getVouchers tag: plumProAPI variables: data: categoryType: merchandise limit: 10 page: 1 includeProducts: '23353' excludeProducts: '1133' exchangeRate: 1 sort: field: name order: ASC responses: '200': description: Merchandise 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 valueType: type: string maxValue: type: number minValue: type: number deliveryType: type: string fee: type: number discount: type: number exchangeRate: type: number isPhoneNumberMandatory: type: boolean '401': $ref: '#/components/responses/Unauthorized' '502': $ref: '#/components/responses/BadGateway' 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 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 `' ````