[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides vtex store components skuselector in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/vtex-io-deprecated-apps)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/guides/vtex-io-deprecated-apps)

---

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/vtex-io-apps)

SKU Selector

[vtex.store-components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components)

Version: 3.178.5

Latest version: 3.178.5

The `sku-selector` block is mainly used in Product Details Pages (PDPs) to display all the SKUs available for a product.

![{"base64":"  ","img":{"width":1860,"height":664,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":348509,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-store-components-skuselector-0.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-store-components-skuselector-0.png)

## Configuration

1. Import the `vtex.store-components` app to your theme dependencies in the `manifest.json` file as in the following example:

`1

 "dependencies": {

2

 "vtex.store-components": "3.x"

3

 }

`

1. Add the `sku-selector` block to any child of the `store.product` template (product page). For example:

`1

 "store.product": {

2

 "children": [

3

 "flex-layout.row#product",

4

 ]

5

 },

6

 "flex-layout.row#product": {

7

 "children": [

8

+ "sku-selector"

9

 ]

10

 },

`

1. Then, declare the `sku-selector` block using the props stated in the [Props](#props) table. For example:

`1

 "sku-selector": {

2

 "props": {

3

 "hideImpossibleCombinations": false

4

 }

5

 },

`

### Props

| Prop name                       | Type             | Description                                                                                | Default value                                                                                |
| ------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| classes                         | CustomCSSClasses | Overrides default CSS handles. To better understand how this prop works, please refer to [this documentation](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/css-handles%23usecustomclasses). Please note that this is only helpful if you're using this block as a React component.                                                                                | undefined                                                                                |
| disableUnavailableSelectOptions | boolean          | Whether a product variation that leads to an impossible product combination should be displayed with the disabled attribute when displayMode is set to select. By default, all select options are configured without the disabled attribute set based on the type of variation                                                                                | false                                                                                |
| displayMode                     | enum             | Defines how the product variation names will be displayed (it does not apply to product variation images). Possible values are: default (displays all variation names), select (only displays the selected variation name), or slider (displays all variation names in a slider when the number of available options is greater than the value defined in the sliderDisplayThreshold prop). Please note that this prop is _responsive_, so you can declare an object as its value, specifying a value for each breakpoint (desktop and mobile).        | default                                                                                |
| hideImpossibleCombinations      | boolean          | Defines whether a product variation should be clickable (true) or (false). The variation will not be displayed if true. If false, the variation will be displayed with less opacity. For example, there are two colors for a pair of sneakers: pink and white. If the pink sneaker is only available in one size, the other sizes will not be displayed (true).                                                                                | true                                                                                |
| sortVariationsByLabel           | boolean          | Defines if the variations are to be sorted in alphabetical order.                                                                                | false                                                                                |
| imageHeight                     | number           | object                                                                                | Height (in px) of the product thumbnail image. You can declare an object as its value in case you want to define a height for each device (desktop and mobile). |
| imageWidth                      | number           | object                                                                                | Width (in px) of the product thumbnail image. You can declare an object as its value in case you want to define a width for each device (desktop and mobile).   |
| initialSelection                | enum             | Controls the user's initial selection for available variations when the product page is fully loaded. Possible values are: complete (selects the first available SKU variation values), image (selects the first available image variation), or empty (no variations will be selected when the page is loaded).                                                                                | complete                                                                                |
| maxItems                        | number           | The maximum number of variation items to be displayed in the SKU selector before the See more button. The button will always be displayed 2 items before the number set in maxItems.                                                                                | 10                                                                                |
| showValueForVariation           | enum             | Displays a value for the selected variation. This prop replaces the former showValueNameForImageVariation (deprecated). Possible values are: none (no values are displayed when the variation is selected), image (displays only the image value for the selected variation, if any), or all (all variation values are displayed).                                                                                | none                                                                                |
| sliderArrowSize                 | number           | Controls the size (height and width) in pixels of the navigation arrows rendered when displayMode is set as slider.                                                                                | 12                                                                                |
| sliderDisplayThreshold          | number           | The minimum number of product variation names that should be displayed using slider display mode. This prop only works properly when displayMode is set as slider.                                                                                | 3                                                                                |
| sliderItemsPerPage              | object           | Controls how many slides should be displayed on each type of device when displayMode is set as slider. There is more information regarding this prop structure below this table.                                                                                | {desktop: 3, tablet: 2, phone: 1}                                                                                |
| showVariationsErrorMessage      | boolean          | Whether an error message should be displayed when the BuyButton is clicked but no available variation was selected (true) or (false).                                                                                | true                                                                                |
| showVariationsLabels            | enum             | Where variation names should be displayed. Possible values are: none (does not display the variation names). Replaces the previous false behavior), variation (displays the variation name as a header of the items. Replaces the previous true behavior), itemValue (displays the variation name before each item's value), and variationAndItemValue (behaves as variation and itemValue at the same time).                                                                                | variation                                                                                |
| thumbnailImage                  | string           | The first image to be displayed. This prop value must be the same text string defined in the desired product image imageLabel field (from the Catalog module). If you use this prop and no image declaring the same text string in its imageLabel field is found, any product image will be randomly rendered. To apply the thumbnailImage configuration, please read the [Configuring custom images for the SKU Selector documentation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-configuring-custom-images-for-the-sku-selector) | undefined                                                                                |
| variationsSpacing               | number           | Defines the margin-bottom size to be applied in the rendered product variations. Possible values range from 0 to 11 (the prop value is not in px; every value represents a tachyon class).                                                                                | 7                                                                                |
| visibility                      | enum             | Defines the scenarios in which the SKU selector should be displayed. Possible values are: always (it will always be displayed, even if the product has only one SKU option) or more-than-one (the SKU selector is only displayed when the product has more than one SKU option).                                                                                | always                                                                                |
| visibleVariations               | array            | Specifies which product variations should be displayed on the product details page. Please note that no variations will be displayed if you declare a name that does not represent a real product variation or an empty array. There is more information regarding this prop structure below this table.                                                                                | undefined                                                                                |

* **`visibleVariations` props**

| Prop name | Type   | Description             | Default value |
| --------- | ------ | ----------------------- | ------------- |
| name      | string | Product variation name. | undefined     |

* **`sliderItemsPerPage` props**

| Prop name | Type   | Description                                                                                | Default value |
| --------- | ------ | ------------------------------------------------------------------------------------------ | ------------- |
| desktop   | number | The number of slides to be displayed on desktop devices when displayMode is set as slider. | 3             |
| tablet    | number | The number of slides to be displayed on tablet devices when displayMode is set as slider.  | 2             |
| phone     | number | The number of slides to be displayed on phone devices when displayMode is set as slider.   | 1             |

## Customization

To apply CSS customizations to this and other blocks, please see the [Using CSS handles for store customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization) guide.

| CSS Handles                   |
| ----------------------------- |
| frameAround                   |
| seeMoreButton                 |
| skuSelectorContainer          |
| skuSelectorInternalBox        |
| skuSelectorItemImageValue     |
| skuSelectorItemImage          |
| skuSelectorItemTextValue      |
| skuSelectorItem               |
| skuSelectorNameContainer      |
| skuSelectorNameSeparator      |
| skuSelectorName               |
| skuSelectorOptionsList        |
| skuSelectorSelectorImageValue |
| skuSelectorSubcontainer       |
| skuSelectorTextContainer      |
| valueWrapper                  |

See also

[Vtex.store ComponentsVTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/apps/vtex.store-components)[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)

ON THIS PAGE

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/apps/vtex.store-components/SKUSelector%23configuration)

[Props](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/apps/vtex.store-components/SKUSelector%23props)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-skuselector/docs/apps/vtex.store-components/SKUSelector%23customization)

Was this helpful?

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides managing vtex gift cards in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/getting-started)

---

Integration Guides

[Back office integration guide (ERP/PIM/WMS)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/erp-integration-guide)

[Customer Credit](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/customer-credit-integration-guide)

[External Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/external-marketplace-integration-guide)

[External Seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/external-seller-integration-guide)

[Gift Card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/gift-card-integration-guide)

[Gift Card system architecture](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/gift-card-integration-guide-system-architecture)

[Managing VTEX gift cards](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards)

[Headless commerce](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/headless-commerce)

[Login (SSO)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/login-integration-guide)

[Punchout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/punchout)

[Offer Management Integration Guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/sent-offers-integration-guide-connectors)

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/payments-integration-guide)

[Search Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/search-integration-guide)

[Session Manager](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/session-manager)

[Tax Service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/tax-service-integration-guide)

[Pricing Hub](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/pricing-hub)

[reCAPTCHA](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/recaptcha)

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/getting-started)

---

Integration Guides

[Back office integration guide (ERP/PIM/WMS)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/erp-integration-guide)

[Customer Credit](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/customer-credit-integration-guide)

[External Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/external-marketplace-integration-guide)

[External Seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/external-seller-integration-guide)

[Gift Card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/gift-card-integration-guide)

[Gift Card system architecture](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/gift-card-integration-guide-system-architecture)

[Managing VTEX gift cards](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards)

[Headless commerce](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/headless-commerce)

[Login (SSO)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/login-integration-guide)

[Punchout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/punchout)

[Offer Management Integration Guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/sent-offers-integration-guide-connectors)

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/payments-integration-guide)

[Search Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/search-integration-guide)

[Session Manager](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/session-manager)

[Tax Service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/tax-service-integration-guide)

[Pricing Hub](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/pricing-hub)

[reCAPTCHA](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/recaptcha)

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides)

Integration Guides

[Gift Card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/gift-card-integration-guide)

[Managing VTEX gift cards](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards)

Managing VTEX gift cards

This guide describes how to manage VTEX native gift cards from the VTEX gift card provider through the [GiftCard API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23overview). With this API, you can perform the following actions:

* [Create a VTEX gift card](#creating-a-vtex-gift-card)
* [Check VTEX gift card details](#checking-vtex-gift-card-details)
* [Create VTEX gift card transactions](#creating-vtex-gift-card-transactions)
* [Check VTEX gift card transactions](#checking-vtex-gift-card-transactions)
* [Cancel a VTEX gift card transaction](#cancelling-a-vtex-gift-card-transaction)

> You can also manage VTEX gift cards using your store Admin. For more information, see [Setting up Gift Cards](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/gift-card--tutorials%5F995).

## Creating a VTEX gift card

To create a VTEX gift card, you can use the [Create GiftCard](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23post-/giftcards) endpoint. In this request, you must send the information of the gift card you want to create.

**POST**

`https://{accountName}.{environment}.com.br/api/giftcards`

Request body

`1

{

2

 "relationName": "loyalty-program-test",

3

 "expiringDate": "2024-01-01T00:00:00",

4

 "caption": "Vtex Loyalty Test",

5

 "profileId": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff",

6

 "restrictedToOwner": false,

7

 "currencyCode": "BRL",

8

 "multipleCredits": true,

9

 "multipleRedemptions": false

10

}

`

The endpoint will return some of the previously sent detailsand new information about the created gift card, such as:

* `"id"`: gift card identification.
* `"redemptionToken"`: gift card redemption token.
* `"redemptionCode"`: gift card redemption code.
* `"balance"`: gift card balance.
* `"emissionDate"`: gift card issue date.
* `"transaction"`: transaction code for the create gift card operation.

Response body

`1

{

2

 "id": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",

3

 "redemptionToken": "COCW-OZYZ-BEXN-TIMU",

4

 "redemptionCode": "COCW-OZYZ-BEXN-TIMU",

5

 "balance": 0.0,

6

 "relationName": "loyalty-program-test",

7

 "emissionDate": "2023-08-23T16:20:01.0479856Z",

8

 "expiringDate": "2024-01-01T00:00:00",

9

 "caption": "Vtex Loyal Test",

10

 "currencyCode": "BRL",

11

 "discount": false,

12

 "transaction": {

13

 "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions"

14

 }

15

}

`

You can also access your store Admin (**Promotions > Gift Cards**) to confirm that the new gift card was created.

![{"base64":"  ","img":{"width":1816,"height":203,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":71810,"url":"https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/guides/Integration-Guides/gift-card-integration-guide/managing-vtex-gift-cards_1.png"}}](https://read.calvincode.net/reader?url=https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/guides/Integration-Guides/gift-card-integration-guide/managing-vtex-gift-cards_1.png)

> All gift cards created via API have no balance (value 0). You can add balance amounts to new gift cards through the [Create GiftCard Transaction](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23post-/giftcards/-giftCardID-/transactions) endpoint or the VTEX Admin.

## Checking VTEX gift card details

When you want to check details about a specific gift card, you can use the [Get GiftCard by ID](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23get-/giftcards/-giftCardID-) endpoint. In this request, you must send the gift card identification (`giftCardId`) as a path parameter.

See an example below using gift card `92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74`:

**GET**

`https://{accountName}.{environment}.com.br/api/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74`

Response body

`1

{

2

 "id": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",

3

 "redemptionToken": "COCW-OZYZ-BEXN-TIMU",

4

 "redemptionCode": "COCW-OZYZ-BEXN-TIMU",

5

 "balance": 0.0,

6

 "relationName": "loyalty-program-test",

7

 "emissionDate": "2023-08-23T16:20:01.047",

8

 "expiringDate": "2024-01-01T00:00:00",

9

 "caption": "Vtex Loyal Test",

10

 "currencyCode": "BRL",

11

 "discount": false,

12

 "transaction": {

13

 "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions"

14

 }

15

}

`

> You can also check the information of a VTEX gift card using the VTEX Admin. For more information, go to **Promotions > Gift Cards > Search or Filter Results**.

## Creating VTEX gift card transactions

A gift card transaction is a record of an operation that changes the gift card balance, such as a purchase or a refund. To change balance values, you can use the [Create GiftCard Transaction](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23post-/giftcards/-giftCardID-/transactions) endpoint.

The sections below show a simulation of how to make the following changes to a gift card balance:

* Add 500 USD
* Spend 120 USD

### Adding balance to a gift card

You can use the [Create GiftCard Transaction](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23post-/giftcards/-giftCardID-/transactions) endpoint to add balance to a gift card. In this request, you must send the gift card identification (`giftCardId`) as a path parameter.

See an example below using gift card `92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74`.

**POST**

`https://{accountName}.{environment}.com.br/api/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions`

To indicate that you wish to add 500 USD to your balance, send "Credit" in the "operation" field and 500 in the "value" field.

Request body

`1

{

2

 "operation": "Credit",

3

 "value": 500,

4

 "description": "Opening balance",

5

 "redemptionToken": "COCW-OZYZ-BEXN-TIMU",

6

 "redemptionCode": "COCW-OZYZ-BEXN-TIMU",

7

 "requestId": "1"

8

}

`

Response body

`1

{

2

 "cardId": "74",

3

 "id": "465f2d7370f349879f4c194ac81d8e98",

4

 "_self": {

5

 "href": "cosmetics2/giftcards/74/transactions/465f2d7370f349879f4c194ac81d8e98"

6

 }

7

}

`

To confirm the new gift card balance, use the [Get GiftCard by ID](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23get-/giftcards/-giftCardID-) endpoint or the Admin dashboard.

Response body

`1

{

2

 "id": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",

3

 "redemptionToken": "COCW-OZYZ-BEXN-TIMU",

4

 "redemptionCode": "COCW-OZYZ-BEXN-TIMU",

5

 "balance": 500.0000,

6

 "relationName": "loyalty-program-test",

7

 "emissionDate": "2023-08-23T16:20:01.047",

8

 "expiringDate": "2024-01-01T00:00:00",

9

 "caption": "Vtex Loyal Test",

10

 "currencyCode": "BRL",

11

 "discount": false,

12

 "transaction": {

13

 "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions"

14

 }

15

}

`

Admin

![{"base64":"  ","img":{"width":1817,"height":199,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":73771,"url":"https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/guides/Integration-Guides/gift-card-integration-guide/managing-vtex-gift-cards_2.png"}}](https://read.calvincode.net/reader?url=https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/guides/Integration-Guides/gift-card-integration-guide/managing-vtex-gift-cards_2.png)

### Removing balance from a gift card

To remove balance from a gift card, you must also use the [Create GiftCard Transaction](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23post-/giftcards/-giftCardID-/transactions) endpoint and send the gift card identification (`giftCardId`) as a path parameter.

See an example below using gift card `92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74`.

**POST**

`https://{accountName}.{environment}.com.br/api/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions`

To indicate that you wish to remove 120 USD from your balance, send the information "Debit" in the "operation" field and 120 in the "value" field.

Request body

`1

{

2

 "operation": "Debit",

3

 "value": 120,

4

 "description": "Payment of order 5555",

5

 "redemptionToken": "COCW-OZYZ-BEXN-TIMU",

6

 "redemptionCode": "COCW-OZYZ-BEXN-TIMU",

7

 "requestId": "2"

8

}

`

Response body

`1

{

2

 "cardId": "74",

3

 "id": "c2b69a5990404a11b26888964bed3868",

4

 "_self": {

5

 "href": "cosmetics2/giftcards/74/transactions/c2b69a5990404a11b26888964bed3868"

6

 }

7

}

`

> Whenever you create a new transaction, you must send a `requestId` different from the ones previously used for that gift card. Transactions that have a `requestId` value previously used on the same gift card will not be completed. Example: After creating the first credit transaction, in which you used the value "1" for `requestId`, you create a debit transaction with `requestId` equal to "2". Any other transaction for this gift card must be created with values different from "1" and "2" in the `requestId`.

To confirm the new gift card balance, use the Get GiftCard by ID endpoint or Admin dashboard.

Response body

`1

{

2

 "id": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",

3

 "redemptionToken": "COCW-OZYZ-BEXN-TIMU",

4

 "redemptionCode": "COCW-OZYZ-BEXN-TIMU",

5

 "balance": 380.0000,

6

 "relationName": "loyalty-program-test",

7

 "emissionDate": "2023-08-23T16:20:01.047",

8

 "expiringDate": "2024-01-01T00:00:00",

9

 "caption": "Vtex Loyal Test",

10

 "currencyCode": "BRL",

11

 "discount": false,

12

 "transaction": {

13

 "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions"

14

 }

15

}

`

Admin

![{"base64":"  ","img":{"width":1819,"height":200,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":73925,"url":"https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/guides/Integration-Guides/gift-card-integration-guide/managing-vtex-gift-cards_3.png"}}](https://read.calvincode.net/reader?url=https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/guides/Integration-Guides/gift-card-integration-guide/managing-vtex-gift-cards_3.png)

## Checking VTEX gift card transactions

You can use the [List All GiftCard Transactions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23get-/giftcards/-giftCardID-/transactions) endpoint to check all transactions performed on a gift card. In this request, you must send the gift card identification (`giftCardId`) as a path parameter.

See an example below using gift card `92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74`.

**GET**

`https://{accountName}.{environment}.com.br/api/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions`

Response body showing information from two transactions:

`1

[

2

 {

3

 "cardId": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",

4

 "id": "c2b69a5990404a11b26888964bed3868",

5

 "_self": {

6

 "href": "cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions/c2b69a5990404a11b26888964bed3868"

7

 }

8

 },

9

 {

10

 "cardId": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",

11

 "id": "465f2d7370f349879f4c194ac81d8e98",

12

 "_self": {

13

 "href": "cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions/465f2d7370f349879f4c194ac81d8e98"

14

 }

15

 }

16

]

`

> If you use this endpoint to request details for a new gift card (which does not yet contain transactions), the response body will be empty.

### Accessing information from a gift card transaction

To get information about a specific gift card transaction, you can use the [Get GiftCard Transaction by ID](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23get-/giftcards/-giftCardID-/transactions/-transactionID-) endpoint. In this request, you must send the gift card identification (`giftCardId`) and transaction operation (`transactionId`) identification as path parameters.

> The `transactionID` value used in this request is the same id value obtained from the response body of the [List All GiftCard Transactions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23get-/giftcards/-giftCardID-/transactions) endpoint. For more information, see the [Checking VTEX gift card transactions](#checking-vtex-gift-card-transactions) section.

See an example below using gift card `92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74` and transaction operation `18f71495d720497cb77dfc521f75087`.

**GET**

`https://{accountName}.{environment}.com.br/api/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_73/transactions/18f71495d720497cb77dfc521f750877`

Response body

`1

{

2

 "value": 58.0,

3

 "description": "Add 58 BRL",

4

 "date": "2023-08-22T22:16:23.2974622Z",

5

 "requestId": "10",

6

 "settlement": {

7

 "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_73/transactions/18f71495d720497cb77dfc521f750877/settlements"

8

 },

9

 "cancellation": {

10

 "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_73/transactions/18f71495d720497cb77dfc521f750877/cancellations"

11

 },

12

 "authorization": {

13

 "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_73/transactions/18f71495d720497cb77dfc521f750877/authorization"

14

 },

15

 "operation": "Credit"

16

}

`

## Cancelling a VTEX gift card transaction

To partially or completely cancel a value assigned in a transaction (credit or debit), you can use the [Cancel GiftCard Transaction](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23post-/giftcards/-giftCardID-/transactions/-transactionID-/cancellations) endpoint. In this request, you must send the gift card identification (`giftCardId`) and transaction operation (`transactionId`) identification as path parameters.

> The transactionId value used in this request is the same id value obtained from the response body of the List All GiftCard Transactions endpoint. For more information, see the Checking VTEX gift card transactions section.

The example below shows how to partially cancel a debit transaction (`c2b69a5990404a11b26888964bed3868`). The transaction value is 120 USD and the canceled amount will be 20 USD. The gift card used is `92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74` (current balance of 380 USD).

**POST**

`https://{accountName}.{environment}.com.br/api/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions/c2b69a5990404a11b26888964bed3868/cancellations`

To indicate that you want to cancel the amount of 20 USD in the debit transaction, send 20 in the "value" field.

Request body

`1

{

2

 "value": 20,

3

 "requestId": "4"

4

}

`

Response body

`1

{

2

 "oid": "a1e7edfb72d74bfa960cdbc2eb9471ce",

3

 "value": 20.0,

4

 "date": "2023-08-23T17:28:39.7212872Z"

5

}

`

To confirm the new gift card balance, use the [Get GiftCard by ID](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/giftcard-api%23get-/giftcards/-giftCardID-) endpoint or the Admin dashboard.

Response body

`1

{

2

 "id": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74",

3

 "redemptionToken": "COCW-OZYZ-BEXN-TIMU",

4

 "redemptionCode": "COCW-OZYZ-BEXN-TIMU",

5

 "balance": 400.0000,

6

 "relationName": "loyalty-program-test",

7

 "emissionDate": "2023-08-23T16:20:01.047",

8

 "expiringDate": "2024-01-01T00:00:00",

9

 "caption": "Vtex Loyal Test",

10

 "currencyCode": "BRL",

11

 "discount": false,

12

 "transaction": {

13

 "href": "/cosmetics2/giftcards/92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff_74/transactions"

14

 }

15

}

`

Admin

![{"base64":"  ","img":{"width":1817,"height":195,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":72401,"url":"https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/guides/Integration-Guides/gift-card-integration-guide/managing-vtex-gift-cards_4.png"}}](https://read.calvincode.net/reader?url=https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/guides/Integration-Guides/gift-card-integration-guide/managing-vtex-gift-cards_4.png)

> When a debit transaction is canceled, the canceled amount is credited to the total gift card balance. Likewise, when a credit transaction is canceled, the canceled amount is debited from the total gift card balance.

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F87548049%3Fv%3D4%26w=64%26q=75)](https://github.com/ricardoaerobr)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Integration-Guides/gift-card-integration-guide/managing-vtex-gift-cards.md)

[Gift Card system architecture« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards//docs/guides/gift-card-integration-guide-system-architecture)[Headless commerceNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards//docs/guides/headless-commerce)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F87548049%3Fv%3D4%26w=64%26q=75)](https://github.com/ricardoaerobr)

ON THIS PAGE

[Creating a VTEX gift card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23creating-a-vtex-gift-card)

[Checking VTEX gift card details](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23checking-vtex-gift-card-details)

[Creating VTEX gift card transactions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23creating-vtex-gift-card-transactions)

[Adding balance to a gift card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23adding-balance-to-a-gift-card)[Removing balance from a gift card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23removing-balance-from-a-gift-card)

[Checking VTEX gift card transactions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23checking-vtex-gift-card-transactions)

[Accessing information from a gift card transaction](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23accessing-information-from-a-gift-card-transaction)

[Cancelling a VTEX gift card transaction](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23cancelling-a-vtex-gift-card-transaction)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Integration-Guides/gift-card-integration-guide/managing-vtex-gift-cards.md)

Copy page

On this page

ON THIS PAGE

[Creating a VTEX gift card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23creating-a-vtex-gift-card)

[Checking VTEX gift card details](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23checking-vtex-gift-card-details)

[Creating VTEX gift card transactions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23creating-vtex-gift-card-transactions)

[Adding balance to a gift card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23adding-balance-to-a-gift-card)[Removing balance from a gift card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23removing-balance-from-a-gift-card)

[Checking VTEX gift card transactions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23checking-vtex-gift-card-transactions)

[Accessing information from a gift card transaction](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23accessing-information-from-a-gift-card-transaction)

[Cancelling a VTEX gift card transaction](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/managing-vtex-gift-cards/docs/guides/managing-vtex-gift-cards%23cancelling-a-vtex-gift-card-transaction)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides vtex io documentation using css handles for store customization in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework)

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-using-advanced-layouts)

[Working with Site Editor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-working-with-site-editor)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-styling)

[Using CSS Handles for store customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization)

[Contributing with new CSS Handles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-contributing-with-new-css-handles)

[Customizing your store's icons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-customizing-your-stores-icons)

[Customizing your store’s typography](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-customizing-your-stores-typography)

[Interactively inspecting storefront blocks](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/how-to-interactively-inspect-blocks-on-a-store-framework-store)

[Using the Markers prop to customize a block's message](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-the-markers-prop-to-customize-a-blocks-message)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-dealing-with-events)

[Configuring Analytics (Google Tag Manager)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-configuring-analytics-google-tag-manager)

[Setting up cross-border stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-setting-up-cross-border-stores)

[Handling internationalization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-managing-performance)

[Improving store accessibility with semantic HTML migration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-semantic-html-migration)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-go-live)

[Updating live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-updating-live-stores)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework)

[Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-store-theme)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/getting-started-3)

Concepts

[Building pages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-building-pages)

[Using components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-using-components)

[Using advanced layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-using-advanced-layouts)

[Working with Site Editor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-working-with-site-editor)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-styling)

[Using CSS Handles for store customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization)

[Contributing with new CSS Handles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-contributing-with-new-css-handles)

[Customizing your store's icons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-customizing-your-stores-icons)

[Customizing your store’s typography](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-customizing-your-stores-typography)

[Interactively inspecting storefront blocks](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/how-to-interactively-inspect-blocks-on-a-store-framework-store)

[Using the Markers prop to customize a block's message](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-the-markers-prop-to-customize-a-blocks-message)

[Dealing with events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-dealing-with-events)

[Configuring Analytics (Google Tag Manager)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-configuring-analytics-google-tag-manager)

[Setting up cross-border stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-setting-up-cross-border-stores)

[Handling internationalization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-multi-language-stores)

[Routing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-routing)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-managing-performance)

[Improving store accessibility with semantic HTML migration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-semantic-html-migration)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-go-live)

[Updating live stores](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-updating-live-stores)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/storefront-best-practices)

---

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/storefront-development)

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/store-framework-styling)

[Using CSS Handles for store customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization)

Using CSS handles for store customizations

Learn how to customize your storefront using CSS handles.

In this guide, you'll learn how to customize your storefront using CSS handles. These unique identifiers assigned to HTML elements allow you to target and add CSS classes to a component within your [Store Theme](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-store-theme).

CSS handles can overwrite a storefront's default styles, allowing for independent customization of specific blocks within a Store Theme. For example, consider you want to customize the `menu-item` blocks of the [Menu](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.menu) component. You can apply a [general customization](#applying-a-general-customization) or [customize a single block](#customizing-a-single-block).

## Instructions

### Identifying CSS handles

1. Open your browser and go to your store's development workspace using this URL: `https://{workspace}--{account}.myvtex.com?__inspect`. Replace the values inside curly braces with your specific workspace and account names.

> Always use a development workspace and make sure your store domain is under `myvtex.com`.

1. Hover your mouse over the page element you want to customize. A box will appear displaying its available CSS handles (names starting with `.`), CSS file names, and related information.

![{"base64":"  ","img":{"width":2294,"height":1730,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":1181747,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-using-css-handles-for-store-customization-0.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-using-css-handles-for-store-customization-0.png)

1. Check the CSS handles table in the documentation of the app or block that renders the HTML element. This allows you to confirm whether the inspected handle is valid and if the customization requires another add-on, such as the HTML element attribute.

> If a handle requires an HTML element attribute for customization, inspect the page again using your browser's developer tools instead of the `?__inspect` option. Find the desired HTML element and copy its associated attribute for the upcoming customization.

### Applying a general customization

Follow the steps below to apply a style that affects every block instance:

1. Open your Store Theme code using the code editor of your choice and go to the `css` folder.
2. In the `css` folder, create a new CSS file named after the component you're targeting. For example, `vtex.menu.css`.
3. In the new file, use one of the listed CSS handles and customize its properties. For example:

`1

.menuItem {

2

 background: rgba(0, 0, 0, 0.2);

3

 margin: 5px;

4

 border-radius: 5px;

5

}

`

> If the handle requires an add-on, such as the HTML element attribute or a handle modifier, add it next to the handle name, following this format: `{cssHandleName}--{addon)`.

1. [Link your app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-linking-an-app) to see the changes. Once linked, the new style applies to all `menu-item` blocks in the workspace you're working on.

![{"base64":"  ","img":{"width":2290,"height":1714,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":1168758,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-using-css-handles-for-store-customization-1.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-using-css-handles-for-store-customization-1.png)

### Customizing a single block

To customize a single, specific block without affecting others of the same type, use the `blockClass` property, which serves as the block's unique identifier for customization:

1. In the `json` file where your target block is declared, add the prop `blockClass` to the element you want to customize. Assign any unique name as its value. For example:

`1

"menu-item#your-item": {

2

 "props": {

3

 ...,

4

 "blockClass": "header"

5

 },

6

 ...

7

}

`

1. Save the file to update the workspace you're working on.
2. Inspect the element by following the instructions in [Identifying CSS handles](#identifying-css-handles). You'll see a new, more specific CSS handle composed of the original handle and the `blockClass` value you provided.

![{"base64":"  ","img":{"width":2288,"height":806,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":239946,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-using-css-handles-for-store-customization-2.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-using-css-handles-for-store-customization-2.png)

1. In your CSS file, you can now use this new class (for example: `.menu-Item--header`) to target only the block with that specific `blockClass`.

![{"base64":"  ","img":{"width":2292,"height":616,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":91378,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-using-css-handles-for-store-customization-3.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-using-css-handles-for-store-customization-3.png)

## Best practices

CSS selectors are commonly used for customization, but this depends on the HTML structure. If you change the HTML, it can affect your customizations. To standardize CSS customization and avoid any potential breakdown in the layout, we recommend only using CSS handles for store customizations.

Customization using CSS selectors is mostly deprecated. The following selectors are the only ones allowed for store customization:

* Class selectors (example: `.foo`)
* Pseudo-selectors `:hover`, `:visited`, `:active`, `:disabled`, `:focus`, `:local`, `:empty`, and `:target`
* `:not()`
* `:first-child` and `:last-child`
* `:nth-child(even)`, `:nth-child(odd)`, and `:nth-child(2n)` (or any other step like `4n`, `5n`, and so on.)
* All pseudo-elements, such as `::before`, `::after`, and `::placeholder`
* Space combinator (example: `.foo .bar`)
* `[data-...]`
* `:global(vtex-{AppName}-{AppVersion}-{ComponentName})` for selecting elements that come from different apps
* Media queries, such as `@media (max-width: 768px)` (responsive override for screens up to 768px wide) and `@media (prefers-reduced-motion: reduce)` (remove transitions if user prefers reduced motion).

> CSS selectors that are not included in this list, such as `:nth-child(2)`, `foo > bar`, and `[alt="bar"]`, aren't supported. Using them can cause issues like app linking failure.

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Storefront-Guides/styling-your-store/vtex-io-documentation-using-css-handles-for-store-customization.md)

[Styling« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization//docs/guides/store-framework-styling)[Contributing with new CSS HandlesNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization//docs/guides/vtex-io-documentation-contributing-with-new-css-handles)

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

ON THIS PAGE

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization%23instructions)

[Identifying CSS handles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization%23identifying-css-handles)[Applying a general customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization%23applying-a-general-customization)[Customizing a single block](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization%23customizing-a-single-block)

[Best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization%23best-practices)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Storefront-Guides/styling-your-store/vtex-io-documentation-using-css-handles-for-store-customization.md)

Copy page

On this page

ON THIS PAGE

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization%23instructions)

[Identifying CSS handles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization%23identifying-css-handles)[Applying a general customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization%23applying-a-general-customization)[Customizing a single block](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization%23customizing-a-single-block)

[Best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization%23best-practices)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides vtex locale switcher in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/updates/release-notes)

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/updates/release-notes)

Locale Switcher

The Locale Switcher app provides a component capable of changing the current language of your store.

![{"base64":"  ","img":{"width":73,"height":152,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":3496,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-locale-switcher-0.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-locale-switcher-0.png)

## Configuration

1. Add the Locale Switcher app to your theme's dependencies in the `manifest.json` file:

`1

 "dependencies": {

2

+ "vtex.locale-switcher": "0.x"

3

 }

`

1. Add the `locale-switcher` block to your header. For example:

`1

"header-row#desktop": {

2

 "children": [

3

 // (...)

4

 "locale-switcher",

5

 "login",

6

 "minicart.v2"

7

 ]

8

},

`

1. Open a ticket to our support team in order to adjust your store's binding with the desired languages.

> **\*Caution:** The third step is mandatory. If no ticket is opened requiring the desired languages, the selection list may not appear on the Locale Switcher component.\*

## Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on [Using CSS Handles for store customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization).

| CSS Handles       |
| ----------------- |
| button            |
| buttonText        |
| container         |
| list              |
| listElement       |
| localeIdText      |
| relativeContainer |

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Store-Framework-Apps/basic-components/vtex-locale-switcher.md)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

ON THIS PAGE

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/guides/vtex-locale-switcher%23configuration)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/guides/vtex-locale-switcher%23customization)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Store-Framework-Apps/basic-components/vtex-locale-switcher.md)

Copy page

On this page

ON THIS PAGE

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/guides/vtex-locale-switcher%23configuration)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-locale-switcher/docs/guides/vtex-locale-switcher%23customization)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)