A gift list is a list of products that a shopper creates and sends to guests (other shoppers) asking them to buy the products. This can be useful for events like birthdays, weddings, and baby showers. When a guest buys one or more products from the list, virtual credit is generated that can be converted into a gift card. The list’s creator has a wallet with information about the generated credit and the gift card. Then, the creator of the list can use the gift card to purchase the desired items.
The Gift List app allows you to create an environment that contains gift lists. In this environment, shoppers can create gift lists, send them to guests, manage credit on their wallets, and see their bank statements. This app makes an Admin interface available where the shopkeeper can manage the progress of the lists, with information like the number of lists created, track information from multiple customers, and how much money was generated from the gift lists among other essential measures.
The gift cards used in gift lists are VTEX native ones. Gift cards from external providers are not supported by the app.
Getting started
The Gift List app must run in an environment separate from the main store. So first you need to create a subaccount inside the main account. You can check the instructions in the How to create a multistore / multidomain article.
After creating the subaccount, it is necessary to open a ticket to the VTEX support team requesting the installation of the vtex.edition-store@5.x
app at the new subaccount. See the Edition App article for more information.
Another requirement is to create an application key on your subaccount to configure the order hook. You can check the instructions in the Application Keys article. You also need to add a role to the application key with access to the Feed v3 and Hook Admin resource. You can check the instructions to create and manage roles in the Roles article.
Remember to save the app key and the app token for further configuration steps.
Setup
To set up Gift List in your store, follow these steps:
- Install the Gift List app. You can do this by going to the List app page and acquiring the app in the subaccount created previously.
- Access your subaccount Admin.
- Access the Gift List App Settings menu. The conversion of the values received from the gifts will be sent to a Gift Voucher that can be used in your official store. But for that, we have to configure it. When accessing the previously specified menu, the following screen will be displayed:
- In the Account Setting tab, click on the Main account name field and choose the account which is the official store where the generated gift cards will be used.
- Click on the
SAVE
button. - Go to the Advanced Settings tab.
- Use the app key and the app token created previously in the VTEX App Key and VTEX App Token fields respectively for the order hook. This application key must have no hook registered to it.
- Click on the
SAVE
button. - In the left panel of the Admin, go to Search > Integration Configuration. Here you will configure the Intelligent Search so that your entire store catalog is indexed in the subaccount.
Click on the
START INTEGRATION
button and wait until all the integration is completed successfully as shown in the image below.After these steps, the app is configured and the gift lists are available in the store for the shoppers.
Components
Below is a list of all the components in our app:
Add To Cart Button
Add to List Button
Auth Condition
Add New Item
Breadcrumbs
List Modal
Gallery List Items
Gifted Button
Go Back To List
List Info
list-info.name
, list-info.event-date
and list-info.owner
) and each one represents a type of information associated with the list, which are the name of the list, date of the event and name of the owner of the list respectively. Product Modal
Autocomplete Result List
Quantity Selector
quantity-selector-minicart
, quantity-selector-shelf-guest
and quantity-selector-shelf-owner-list
) and each of them represents a quantity selector for different contexts which are use in mini-cart, guest shelf, list owner shelf and selection modal on search page. Search List
Store Wallet List
Share List
Users List
Wrappers
wner-list-wrapper
, guest-list-wrapper
and user-lists-wrapper
) and each one represents a context, which are owners, guests and users respectively. List Items Order By
Optional settings (recommended)
Trade Policy
To better control the functioning of the gift list, we strongly recommend creating a new trade policy. There are 3 main reasons why trade policy helps you to manage gift lists:
- Stock control: There are two different moments of purchase on gift flow. The first occurs when guests realize a purchase related to the list. The second occurs when the list owner realizes a purchase, using the credits received by the guests on the first purchase.
Because of this flow, two items can be removed for the same gift, generating an imbalance in stock control. Attentive to this problem, we suggest one stock to be used only for gift list purchases. For this matter, is mandatory an exclusive trade policy for linking stock with the store catalog. - Specific assortment: You could want to define a specific assortment of items to be added to clients' lists. For this purpose, you will need a separate trade policy.
- Different prices: Another common situation is to define a specific price table for items sold by gift list. A new trade policy helps you to enable this particular price table.
To create a new trade policy, please fill out this form. If you want more information about commercial policies, check the Creating a trade policy article on our Help Center.
Ready-made theme
It is possible to use a ready-made theme with these components or even use this theme and then change it to meet your needs better. If you want to use the mentioned theme, you can access it on the List Theme repository or install it directly using the command:
vtex install vtex.list-theme@3.x
After the theme is created, it will be necessary to enter the Site Editor in the Admin to add which category the list owner will be redirected to when adding a product to your list, as can be seen below:

Checkout
We recommend using the checkout created by us for the gift list, as it will allow some personalized features to be added, such as the possibility of sending personalized emails from a guest to the person to be gifted. To use it, just install it with the following command:
vtex install vtex.list-checkout@0.x
If you continue with this alternative, you will also need to install the checkout-ui-custom
app if you want to edit the previous checkout. The steps to use this application can be found in the Checkout UI Custom article.
With the checkout apps installed, you can enable the message field. To do this, just access the Checkout UI Custom interface via Admin and upload the following snippet in the CSS tab and publish the changes.
.note { display: block; }

Login integration with the main account
Another recommendation is to unify the login of the main account with the subaccount. With this, you can provide a unified navigation experience, since a login into the subaccount will also be a login into the main account and vice versa. You can check the instructions for this configuration in the Unifying login for different accounts article, using the main account as the primary account and the subaccount as the secondary account.
Store owner interface
There is also an interface available for the shopkeeper to follow the metrics obtained by the list application. You can access it on the Admin by going to the Store owner interface menu. In this interface, you will see on the first screen all the users that contain a gift list, with their respective amounts of lists, the value they have already earned in gifts, the value converted into gift vouchers, and whether or not there is already an active list at the moment, respectively. You can also search for emails.

There is also a totalizer with the number of lists, the amount invoiced on the lists, and the converted amount. It is worth adding that if a search is performed or a filter is used, the number of lists and purchased values will be updated according to the result. The search can be done by the list title and the available filters are the status of the lists and the date of creation of the list. Finally, if you want to see the list in question, you can click on the button and you will be redirected to the list in question in the guest view.
