--- title: "Search for coupons" method: POST path: "/api-offers/coupon/search" tags: ["Coupon"] --- # Search for coupons `POST /api-offers/coupon/search` ## Request - Base URL: `https://live.copilot.fabric.inc` - URL: `https://live.copilot.fabric.inc/api-offers/coupon/search` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Use this endpoint to search for coupons based on filter conditions. ## Headers - `x-site-context` string, required ## Request body - SearchPromoRequest: A sample request to search for promotions or coupons. - `offset` number: The number of records to skip before returning records. For example, when offset is 20 and limit is 10, this endpoint returns records from 21 to 30. - `limit` number: The maximum number of records per page. - `sort` '+updatedAt' | '+title' | '+startDate' | '+endDate' | '+level' | '-updatedAt' | '-title' | '-startDate' | '-endDate' | '-level': The criteria to sort the results. Use the format {sort order}{field name}, where `-` refers to a descending order and `+` refers to an ascending order. - `filters` object[] - `field` string, required: Represents the field name or title. If you're searching for Black Friday promotions, this is the `title` of the promotion. - `value` union, required: Represents the value or values corresponding to the `field`. Use Black Friday as value to search for `Black Friday` promotions. - string - union[] - union: This is used to search for multiple values on the same field. - string - number - object - `name` string: The criteria to search based on the name of a segment or additional attributes. - `value` union: The value corresponding to the `name`. It is used to search based on segments or additional attributes. - … - `operator` 'EQUAL' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'IN', required: The type of search operation. You can use multiple values separated by commas for the IN operation. However, you can use only a single value for the EQUALS, GREATER_THAN_OR_EQUAL_TO, and LESS_THAN operations. ## Response `200` OK - PromoSearchResponse: The pagination data. - `query` object - `limit` number: The maximum number of records per page. - `offset` number: The number of records to skip before returning records. For example, when offset is 20 and limit is 10, this endpoint returns records from 21 to 30. - `count` number: The total number of records. - `data` PromoListObject[]: The promotion details. - `_id` string: A 24-character system-generated promotion ID. - `promoId` number: A unique identifier of the promotion, for external use. - `promoCodes` string[]: A list of coupon codes that are applicable only for coupons. For coupons, the response includes promo codes associated with the coupon. For promotions, the response includes an empty array. - `promoCount` number: The number of coupon codes associated with a coupon. This value is always `0` for promotions. - `state` 'ACTIVE' | 'SCHEDULED' | 'DISABLED' | 'EXPIRED': The status of the promotion.
1. `ACTIVE` indicates the promotion is live and available.
2. `SCHEDULED` indicates the promotion is set up and is scheduled to be active in a future date.
3. `DISABLED` indicates the promotion is turned off and can be re-enabled at a later time if required.
4. `EXPIRED` indicates the promotion is no longer valid. - `isImplicit` boolean: A flag indicating whether an offer is applied automatically. Set it to `true` for promotions, which should be applied automatically and `false` for coupons, which must be applied explicitly. - `title` string: The name of the promotion. - `startDate` string, date-time: The start time of the promotion, in UTC format. - `endDate` string, date-time: The end time of the promotion, in UTC format. - `isExclusive` boolean: A flag indicating whether a coupon can be stacked with an existing promotion. Set it to `true` to prevent the coupon from being applied to items that already have promotions and `false` to allow coupon to be applied with existing promotions. - `eligiblePriceList` number[]: The price lists to be considered for the given promotion. - `level` integer: The promotion execution order. Promotion types are assigned default execution orders. Initial evaluation begins with level 1 promotions. The result of level 1 is used as the base price for level 2. Similarly, the result of level 2 becomes the base price for level 3, and so on. - `stackingType` 'STACKABLE' | 'EXCLUSIVE' | 'TYPE_EXCLUSIVE' | 'UNIVERSAL': Defines the rules for how a promotion can be combined with other promotions. This field determines whether a specific promotion can be applied in conjunction with other active promotions during a transaction or if it must be used exclusively. Possible values: - `STACKABLE`: This promotion can be combined with other stackable promotions, allowing multiple discounts to be applied together. The order in which stackable promotions are applied is determined by the `level` field, with promotions having a higher priority (lower numeric value) being applied before those with a lower priority. - `EXCLUSIVE`: This promotion cannot be combined with any other promotions. The `level` field is used to determine which exclusive promotion will be evaluated and applied first. Once an exclusive promotion is applied, no other promotions can be used in the same transaction. - `TYPE_EXCLUSIVE`: This promotion cannot be combined with other promotions of the same type. The `level` field is used to determine which promotion within the same type will be evaluated and applied first. - `UNIVERSAL`: This promotion can be combined with any other promotions without restrictions. Universal promotions will be evaluated last. - `updatedAt` string, date-time: The time when the promotion was last updated, in UTC format. ## Other responses - `400`: Bad Request - `500`: Internal Server Error --- [API](https://skmtc.dev/fabric/apis/offers-v2.md) - [All operations](https://skmtc.dev/fabric/apis/offers-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/fabric/apis/offers-v2/revisions/da2bd742b9bc?raw)