---
title: "Search promotion by name"
method: GET
path: "/api/rnb/pvt/benefits/calculatorconfiguration/search"
tags: ["Promotions and taxes"]
---

# Search promotion by name

`GET /api/rnb/pvt/benefits/calculatorconfiguration/search`

Retrieves all promotions whose name contains the searched term. 

> 📘 Onboarding guide 
>
> Check the new [Promotions onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/promotions-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about the Promotions and is organized by focusing on the developer's journey.



## Permissions

Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:

| **Product** | **Category** | **Resource** |
| --------------- | ----------------- | ----------------- |
| Rates and Benefits | Manage benefits and rates | **GerenciarPromocoesETarifas** |

There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.

## Query parameters

- `byName` string, required

## Headers

- `Content-Type` string, required
- `Accept` string, required

## Response `200`

OK

- object[] — List of promotions whose name matches the search.
  - `idCalculatorConfiguration` string — Promotion ID.
  - `name` string — Promotion Name.
  - `description` string — Promotion internal description.
  - `beginDateUtc` string — Promotion Begin Date (UTC).
  - `endDateUtc` string — Promotion End Date (UTC).
  - `lastModified` string — When the Promotion was last modified.
  - `daysAgoOfPurchases` integer — Number of days that are considered to add the purchase history.
  - `isActive` boolean — If set as `true` the Promotion is activated. If set as `false` the Promotion is deactivated.
  - `isArchived` boolean — If set as `true` the Promotion is archived. If set as `false` the Promotion is not archived.
  - `isFeatured` boolean — Insert a flag with the promotion name used in the product's window display and page.
  - `disableDeal` boolean — Indicates whether a deal is disabled (`true`) or not (`false`).
  - `activeDaysOfWeek` string[] — Defines which days of the week the promotion will applied.
  - `offset` integer — Time offset from UTC in seconds.
  - `activateGiftsMultiplier` boolean — If set as `true`, it activates gifts Multiplier.
  - `newOffset` number — New time offset from UTC in seconds.
  - `maxPricesPerItems` string[] — List of prices per items.
  - `cumulative` boolean — Defines if a promotion can accumulate with another one. (`true`) or not (`false`).
  - `effectType` string — The type of effect that will apply to the promotion.
  - `discountType` string — The type of discount that will apply to the promotion.
  - `nominalShippingDiscountValue` number — Exact discount to be applied for the shipping value.
  - `absoluteShippingDiscountValue` number — Maximum value for the shipping.
  - `nominalDiscountValue` number — Exact discount to be applied for the total purchase value.
  - `nominalDiscountType` string — Controls the behavior of the `NominalDiscount` effect. This field only accepts two string values: -`item`: applies the intended nominal discount on every item present on the cart. -`cart`: keeps the behavior as it currently is: the whole order/cart receives a nominal discount that is distributed among the items.
  - `maximumUnitPriceDiscount` number — The maximum price for each item of the purchase will be the price set up.
  - `percentualDiscountValue` number — Percentage discount to be applied for total purchase value.
  - `rebatePercentualDiscountValue` number — Percentual Shipping Discount Value.
  - `percentualShippingDiscountValue` number — Percentage discount to be applied for shipping value.
  - `percentualTax` number — Percentual tax over purchase total value.
  - `shippingPercentualTax` number — Shipping Percentual tax over purchase total value.
  - `percentualDiscountValueList1` number — Valid discounts for the SKUs in `listSku1BuyTogether`, discount list used for Buy Together Promotions.
  - `percentualDiscountValueList2` number — Equivalent to `percentualDiscountValueList1`.
  - `skusGift` object — SKU Gift Object. Total discount on the product value set as a gift.
    - `quantitySelectable` integer — Quantity of SKU Gifts.
    - `gifts` integer — Array with SKU Gifts IDs.
  - `nominalRewardValue` number — Nominal value for rewards program.
  - `percentualRewardValue` number — Percentage value for rewards program.
  - `orderStatusRewardValue` string — Order status reward value.
  - `maxNumberOfAffectedItems` integer — The maximum number of affected items for a promotion.
  - `maxNumberOfAffectedItemsGroupKey` string — The maximum number of affected items by group key for a promotion.
  - `applyToAllShippings` boolean — Promotion will be applied to all kind of shipping.
  - `nominalTax` number — Nominal tax.
  - `origin` string — Origin of the promotion, `marketplace` or `Fulfillment`. Read [Difference between orders with marketplace and fulfillment sources](https://help.vtex.com/en/tutorial/what-are-orders-with-marketplace-source-and-orders-with-fulfillment-source--6eVYrmUAwMOeKICU2KuG06) for more information.
  - `idSeller` string — Seller Name.
  - `idSellerIsInclusive` boolean — If set to `true`, this promotion will be applied to any seller present on the idSeller field. If set to `false`, sellers present on that field will make this promotion not to be applied.
  - `idsSalesChannel` string[] — List of Trade Policies that activate this promotion.
  - `areSalesChannelIdsExclusive` boolean — If set to `false`, this promotion will be applied to any trade policies present on the `idsSalesChannel` field. If set to `true`, trade policies present on that field will make this promotion not to be applied.
  - `marketingTags` string[] — Promotion Marketing tags.
  - `marketingTagsAreNotInclusive` boolean — If set to `false`, this promotion will be applied to any marketing tag present on the `marketingTags` field. If set to `true`, marketing tags present on that field will make this promotion not to be applied.
  - `paymentsMethods` object[] — Array composed by all the Payments Methods.
    - `id` string — Payment Method ID.
    - `name` string — Payment Method Name.
  - `stores` string[] — List of stores.
  - `campaigns` string[] — Campaign Audiences that activate this promotion.
  - `conditionsIds` string[] — Array with conditions IDs.
  - `storesAreInclusive` boolean — If set to `true`, this promotion will be applied to any store present on the `stores` field. If set to `false`, stores present on that field will make this promotion not to be applied.
  - `categories` object[] — Object composed by the categories that will activate or deactivate the promotion.
    - `id` string — Category ID.
    - `name` string — Category Name.
  - `categoriesAreInclusive` boolean — If set to `true`, this promotion will be applied to any category present on the `categories` field. If set to `false`, categories present on that field will make this promotion not to be applied.
  - `brands` object[] — Object composed by the brands that will activate or deactivate the promotion.
    - `id` string — Brand ID.
    - `name` string — Brand Name.
  - `brandsAreInclusive` boolean — If set to `true`, this promotion will be applied to any brand present on the `brands` field. If set to `false`, brands present on that field will make this promotion not to be applied.
  - `products` object[] — Object composed by the products that will activate or deactivate the promotion.
    - `id` string — Product ID.
    - `name` string — Product Name.
  - `productsAreInclusive` boolean — If set to `true`, this promotion will be applied to any product present on the `products` field. If set to `false`, products present on that field will make this promotion not to be applied.
  - `skus` object[] — Object composed by the SKUs that will activate or deactivate the promotion.
    - `id` string — SKU ID.
    - `name` string — SKU Name.
  - `skusAreInclusive` boolean — If set to `true`, this promotion will be applied to any SKU present on the `skus` field. If set to `false`, SKUs present on that field will make this promotion not to be applied.
  - `utmSource` string — Coupon utmSource code.
  - `utmCampaign` string — Coupon utmCampaign code.
  - `collections1BuyTogether` object[] — Collections that will generate the promotion, type **Buy Together**, **More for less**, **Progressive Discount**, **Buy One Get One**.
    - `id` string — ID of the collection to be added to the first list of the **Buy Together** promotion.
    - `name` string — Name of the collection to be added to the first list of the **Buy Together** promotion.
  - `collections2BuyTogether` object[] — Collections that will generate the promotion, type **Buy Together**, **More for less**, **Progressive Discount** or **Buy One Get One**.
    - `id` string — ID of the collection to be added to the first list of the **Buy Together** promotion.
    - `name` string — Name of the collection to be added to the first list of the **Buy Together** promotion.
  - `minimumQuantityBuyTogether` integer — Minimum quantity for **Buy Together** promotion.
  - `quantityToAffectBuyTogether` integer — Quantity to affect **Buy Together** promotion.
  - `enableBuyTogetherPerSku` boolean — Enable **Buy Together** per SKU.
  - `listSku1BuyTogether` object[] — Array of objects, each containing ID and Name of an SKU to be added in the first list of the **Buy Together** promotion. Learn more about this type of promotion in the [Creating a Buy Together promotion](https://help.vtex.com/en/tutorial/buy-together--tutorials_323) documentation.
    - `id` string — ID of the SKU to be added to the first list of the **Buy Together** promotion.
    - `name` string — Name of the SKU to be added to the first list of the **Buy Together** promotion.
  - `listSku2BuyTogether` object[] — Array of objects, each containing ID and Name of an SKU to be added to the second list of the **Buy Together** promotion. Learn more about this type of promotion in the [Creating a Buy Together promotion](https://help.vtex.com/en/tutorial/buy-together--tutorials_323) documentation.
    - `id` string — ID of the SKU to be added to the second list of the **Buy Together** promotion.
    - `name` string — Name of the SKU to be added to the second list of the **Buy Together** promotion.
  - `coupon` string[] — List of coupons.
  - `totalValueFloor` number — Minimum chart value to activate the promotion.
  - `totalValueCeling` number — Maximum chart value to activate the promotion.
  - `totalValueIncludeAllItems` boolean — Total value including all items.
  - `totalValueMode` string — If products that already are receiving a promotion, will be considered on the chart total value. There are three options available: `IncludeMatchedItems`, `ExcludeMatchedItems`, `AllItems`.
  - `collections` object[] — Array composed by the collections that will be activated or deactivated the promotion.
    - `id` string — Collection ID.
    - `name` string — Collection Name.
  - `collectionsIsInclusive` boolean — If set to `true`, this promotion will be applied to any collection present on the `collections` field. If set to `false`, collections present on that field will make this promotion not to be applied.
  - `restrictionsBins` string[] — The discount will be granted if the card's BIN is given.
  - `cardIssuers` string[] — List of card issuers.
  - `totalValuePurchase` number — Total value a client must have in past orders to active the promotion.
  - `slasIds` string[] — The discount will be granted if the shipping method is the same as the one given.
  - `isSlaSelected` boolean — Applies selected discount only when one of the defined shipping method is selected by the customer.
  - `isFirstBuy` boolean — Applies the discount only if it's a first buy.
  - `firstBuyIsProfileOptimistic` boolean — Applies the discount even if the user is not logged.
  - `compareListPriceAndPrice` boolean — If the **List Price** and **Price** are the same.
  - `isDifferentListPriceAndPrice` boolean — Applies the promotion only if the list price and price is different.
  - `zipCodeRanges` object[] — Range of the zip code that applies the promotion.
    - `zipCodeFrom` string — Initial Zip Code.
    - `zipCodeTo` string — Final Zip Code.
    - `inclusive` boolean — Defines if the zip code range is included in the promotion.
  - `itemMaxPrice` number — Maximum price of the item.
  - `itemMinPrice` number — Minimum price of the item.
  - `installment` integer — Installment.
  - `isMinMaxInstallments` boolean — Set if the promotion will be applied considering a minimum and maximum values for installments.
  - `minInstallment` integer — Minimum value for installment.
  - `maxInstallment` integer — Maximum value for installment.
  - `merchants` string[] — List of merchants.
  - `clusterExpressions` string[] — Criteria to select a customer cluster. Each item in this array should follow the format of an equality function (`{propertyname}={value}`) or the format of a contains function (`{propertyname} contains {value}`). In both options, `{propertyname}` must be replaced with the name of the field in the data entity, and `{value}` must be replaced with the value determined in Master Data. Find more information about these criteria in [Filling in the Customer cluster field](https://help.vtex.com/tutorial/creating-promotion-for-a-customer-cluster--tutorials_342#filling-in-the-customer-cluster-field).
  - `clusterOperator` string — Cluster operator.
  - `paymentsRules` string[] — List of payment rules.
  - `giftListTypes` string[] — Gifts List Type.
  - `productsSpecifications` string[] — List of product specifications.
  - `affiliates` object[] — Marketplace order identifier. The discount will apply to selected affiliates.
    - `id` string — Affiliate ID.
    - `name` string — Affiliate Name.
  - `maxUsage` integer — Defines how many times the promotion can be used.
  - `maxUsagePerClient` integer — Defines if the promotion can be used multiple times per client.
  - `shouldDistributeDiscountAmongMatchedItems` boolean — Should distribute discount among matched items.
  - `multipleUsePerClient` boolean — Defines if the promotion can be used multiple times per client.
  - `accumulateWithManualPrice` boolean — Allows the promotion to apply to products whose prices have been manually added by a call center operator.
  - `type` string — Defines what is the type of the promotion or indicates if it is a tax. Possible values: `regular` ([Regular Promotion](https://help.vtex.com/tutorial/regular-promotion--tutorials_327)), `combo` ([Buy Together](https://help.vtex.com/en/tutorial/buy-together--tutorials_323)), `forThePriceOf` ([More for Less](https://help.vtex.com/en/tutorial/creating-a-more-for-less-promotion--tutorials_325)), `progressive` ([Progressive Discount](https://help.vtex.com/en/tutorial/progressive-discount--tutorials_324)), `buyAndWin` ([Buy One Get One](https://help.vtex.com/en/tutorial/buy-one-get-one--tutorials_322)), `maxPricePerItem` (Deprecated), `campaign` ([Campaign Promotion](https://help.vtex.com/en/tutorial/campaign-promotion--1ChYXhK2AQGuS6wAqS8Ume)), `tax` (Tax), `multipleEffects` (Multiple Effects).
  - `useNewProgressiveAlgorithm` boolean — Use new progressive algorithm.
  - `percentualDiscountValueList` number[] — Percentual discount value list.

---

[API](https://skmtc.net/vtex/apis/promotions-taxes-api.md) · [All operations](https://skmtc.net/vtex/apis/promotions-taxes-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vtex/promotions-taxes-api/revisions/6ad1b4bbb46f/schema)