> ## 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. # Fetch Offers API > Fetch a paginated list of available perks/offers from the catalog. **Note:** This endpoint uses `categoryTypes` (plural) as the filter field, not `categoryType`. **Real URL:** `POST https://stagingstores.xoxoday.com/chef/v1/oauth/api` | **Filter name** | **Functionality** | | :-------------- | :-------------------------------------------------- | | country | Users can filter products based on the country | | productName | Users can filter products based on the product name | | category | Users can filter products based on the categoy | ## Request Parameter | **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 | | sort.field | String | The field name to sort by. | | 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 | | filters.value | String | The filter value corresponding to the key | ## Response Schema | **Path** | **Type** | **Description** | | ------------------------------------------------------- | ------------- | -------------------------------------- | | data | object | Root object. | | data.getVouchers | object | Container for perk data. | | data.getVouchers.status | number | Status of request. | | data.getVouchers.data | array | List of perks. | | data.getVouchers.data\[].productId | number | Unique product/perk ID. | | data.getVouchers.data\[].name | string | Perk name. | | data.getVouchers.data\[].description | string (HTML) | Description of the perk. | | data.getVouchers.data\[].termsAndConditionsInstructions | string (HTML) | T\&C details. | | data.getVouchers.data\[].expiryAndValidity | string (HTML) | Expiry/validity info. | | data.getVouchers.data\[].redemptionInstructions | string (HTML) | Redemption steps. | | data.getVouchers.data\[].categories | string | Category name. | | data.getVouchers.data\[].lastUpdateDate | string | Last updated timestamp. | | data.getVouchers.data\[].imageUrl | string | Perk image URL. | | data.getVouchers.data\[].currencyCode | string | Currency code. | | data.getVouchers.data\[].currencyName | string | Currency name. | | data.getVouchers.data\[].countryName | string | Country applicable. | | data.getVouchers.data\[].countryCode | string | ISO country code. | | data.getVouchers.data\[].countries | array | Applicable countries. | | data.getVouchers.data\[].countries\[].code | string | ISO code. | | data.getVouchers.data\[].countries\[].name | string | Country name. | | data.getVouchers.data\[].valueType | string | Always `fixed_denomination` for perks. | | data.getVouchers.data\[].maxValue | number | Max value (zero for perks). | | data.getVouchers.data\[].minValue | number | Min value. | | data.getVouchers.data\[].valueDenominations | string | Values (often `0`). | | data.getVouchers.data\[].tatInDays | string | Delivery time. | | data.getVouchers.data\[].usageType | string | `online`, `offline`, `both`. | | data.getVouchers.data\[].deliveryType | string | `realtime` | | data.getVouchers.data\[].orderQuantityLimit | number | Max allowed quantity. | | data.getVouchers.data\[].isRecommended | number | Recommended flag. | | data.getVouchers.data\[].filterGroupCode | string | `offer_category` for perks. | | data.getVouchers.data\[].isPhoneNumberMandatory | boolean | Whether phone number is required. | | data.getVouchers.data\[].fee | number | Any fee applied. | | data.getVouchers.data\[].discount | number | Discount if any. | | data.getVouchers.data\[].metadata | object | Perk-specific data block. | | data.getVouchers.data\[].metadata.categorytype | string | Always `offers`. | | data.getVouchers.data\[].metadata.type | string | Perk type (`code`/`link`). | | data.getVouchers.data\[].metadata.code | string | Promo code (if available). | | data.getVouchers.data\[].metadata.link | string | Redirect link. | | data.getVouchers.data\[].metadata.expiryDate | string | Expiry date. | ## Implementation Notes 1. Read the "metadata" field in the `Fetch Offers API` response to get the Offer information like, 2. Code 3. Link 4. Expiry Date of the Code / Link 5. We recommend you cache the response from `Fetch Offers API` in your database every time you sync our catalog > 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-perks.yaml POST /fetchOffers openapi: 3.0.3 info: title: Xoxoday Rewards API – Perks version: '1.2' description: > Perks API endpoints for browsing offers/perks catalog and filtering. Both operations dispatch to `POST /v1/oauth/api` on `stagingstores.xoxoday.com`. Virtual path suffixes are used for playground differentiation. **Notable differences from other Rewards API categories:** - Fetch Filters uses `plumProAPI.mutation.fetchFilters` (not `getFilters`) and accepts `categoryType` and `countryIds` (integer array) - Fetch Offers uses `categoryTypes` (plural string, not `categoryType`) - No balance, order, or payment report endpoints in this category 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 paths: /fetchOffers: post: tags: - Catalog summary: Fetch Offers API description: > Fetch a paginated list of available perks/offers from the catalog. **Note:** This endpoint uses `categoryTypes` (plural) as the filter field, not `categoryType`. **Real URL:** `POST https://stagingstores.xoxoday.com/chef/v1/oauth/api` operationId: perksFetchOffers 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' categoryTypes: type: string enum: - offers default: offers description: Must be `"offers"`. Note the plural field name. sort: type: object properties: field: type: string 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 value: type: string example: query: plumProAPI.mutation.getVouchers tag: plumProAPI variables: data: limit: 10 page: 1 includeProducts: '12345' excludeProducts: '54623' categoryTypes: offers sort: field: name order: ASC responses: '200': description: Perks/offers 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 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 `' ````