--- title: "Search for coupons" method: POST path: "/coupons/search" tags: ["Coupons"] --- # Search for coupons `POST /coupons/search` ## Request - Base URL: `https://api.fabric.inc/v3` - URL: `https://api.fabric.inc/v3/coupons/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-fabric-tenant-id` string, required - `x-fabric-channel-id` string - `x-client-id` string - `x-fabric-request-id` string ## Request body - SearchPromotionRequest: The search criteria. - `size` number: The maximum number of records per page. - `offset` integer: The number of records to skip before returning records. For example, with an offset of 20 and limit of 10, you will get records from 21 to 30. - `sort` '+updatedAt' | '+name' | '+startAt' | '+endAt' | '+level' | '-updatedAt' | '-name' | '-startAt' | '-endAt' | '-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: The name of the field. This is always paired with `value`. - `value` union, required: The value or values corresponding to the `field`. This is always paired with `field`. - string - union[] - union: Search multiple values in the same field. - string - number - object - `name` string: The name to search. This is used to search based on segments or additional attributes. - `value` union: The value corresponding to the `name`. This 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 only use a single value for the EQUALS, GREATER_THAN_OR_EQUAL_TO, and LESS_THAN operations. ## Response `200` OK - SearchPromotionResponse: The search results including the pagination data. - `query` OffsetQuery: Provides pagination data. - `size` integer: The maximum number of records per page. - `offset` integer: The number of records to skip before returning records. For example, with an offset of 20 and limit of 10, you will get records from 21 to 30. - `count` integer: The total number of available records. - `data` PromoSearchObject[]: The response of the search request. - `id` string: The coupon ID generated when using the [create coupon](/v3/api-reference/offers/coupons/create-coupon) endpoint. - `couponCodes` 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. - `couponCodesCount` number: The number of coupon codes associated with a coupon. This value is always `0` for promotions. - `status` 'ACTIVE' | 'SCHEDULED' | 'DISABLED' | 'EXPIRED': The following are possible promotion statuses: - `ACTIVE`: The promotion is live and available. - `SCHEDULED`: The promotion is scheduled to be active at a future date. - `DISABLED`: The promotion is turned off and can be re-enabled later if required. - `EXPIRED`: The promotion is no longer valid. - `name` string: The name of the promotion. - `startAt` string, date-time: The start time of the promotion, in UTC format. - `endAt` string, date-time: The end time of the promotion, in UTC format. - `updatedAt` string, date-time: The time when the promotion was last updated, in UTC format. - `singleMultiUse` 'MULTI_USE' | 'SINGLE_USE': The field to indicate whether it's a single use or multi use coupon - `type` string: The type of coupon promotion you want to create. The following are the coupon promotion types you can create: - `PRODUCT`: A SKU coupon promotion. Applies a discount to SKUs based on the value specified in the `discount` object of the request body. - `CART`: A cart coupon promotion. Applies a discount to the minimum order amount of the cart based on the `ORDER_VALUE` specified in the `condition` object of the request body. - `QUANTITY`: A quantity coupon promotion. Provides discounts on items based on the quantity requirement set in the coupon promotion. - `SHIPPING`: A shipping coupon promotion. Provides discounts on the shipping cost. - `BUYGET`: A BuyGet coupon promotion. Specifies the _Buy_ conditions and corresponding _Get_ discounts. - `SPEND_GET`: A SpendGet coupon promotion. Specifies the total order value required to qualify for discounts and the applicable discounts based on the order value. - `level` number: The level of the promotion to be evaluated. - `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. If configured, `stackingType` will have precedence over the `isStackable` and `isAlwaysApplied` 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 can't 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 can't 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. - `isStackable` boolean: The field to indicate whether the promotion is stackable or not. - `isAlwaysApplied` boolean: The field is true for an universal promotion. - `additionalAttributes` object[]: A placeholder for additional attributes related to promotions, in name-values pairs. - `name` string, required: The attribute name. - `values` union, required: The attribute value or values corresponding to the `name`. - string: The value of the additional attribute. - string[] - `attributeId` number: A unique identifier of the attribute, for external use. - `promotionMessages` object[]: Message description for the promotion - `title` string: Message name - `message` string: Message description - `pages` string[]: The types of web pages where the message is displayed. - `locales` string[]: The locales in which the promotion message is displayed. Locale is a set of language or country-based preferences for user interface. - `proximityMessages` ProximityMessages - `threshold` integer: The proximity threshold value. You muse use a value greater than or equal to 0. - `localizedMessages` object[] - `locales` string[] - `message` string: The localized message for the specified locales. ## Other responses - `400`: Bad request - `401`: Unauthorized - `500`: Internal server error --- [API](https://skmtc.dev/fabric/apis/offers-coupons.md) - [All operations](https://skmtc.dev/fabric/apis/offers-coupons/llms.txt) - [OpenAPI document](https://skmtc.dev/fabric/apis/offers-coupons/revisions/4769f4b9212e?raw)