Documentation
Feedback
Guides
VTEX IO Apps

VTEX IO Apps
Gift List

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:

  1. 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.
  2. Access your subaccount Admin.
  3. 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:
    {"base64":"  ","img":{"width":1999,"height":1027,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":129686,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-gift-list-0.png"}}
  4. 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.
  5. Click on the SAVE button.
  6. Go to the Advanced Settings tab.
  7. 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.
  8. Click on the SAVE button.
    {"base64":"  ","img":{"width":1999,"height":1024,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":136482,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-gift-list-1.png"}}
  9. 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.
    {"base64":"  ","img":{"width":1999,"height":1028,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":178807,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-gift-list-2.png"}}
    Click on the START INTEGRATION button and wait until all the integration is completed successfully as shown in the image below.
    {"base64":"  ","img":{"width":1999,"height":1027,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":157359,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-gift-list-3.png"}}
    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

Displays a button that allows users to add products in the Minicart from a guest page if the quantity purchased has not yet reached the limit.
See more

Add to List Button

Displays a button that allows owners of the list to add products and remove products inside their list.
See more

Auth Condition

Performs validation that the user is logged in to render different layouts.
See more

Add New Item

Displays a button to direct the list owner to the search page for adding new items to their list.
See more

Breadcrumbs

Displays the path to the user's navigation list.
See more

List Modal

Displays a modal for editing or creating lists.
See more

Gallery List Items

Displays the gallery with the products contained in a list.
See more

Gifted Button

Displays the counter of purchases that have already been made for a product within the list.
See more

Go Back To List

Allows the user to return to the list.
See more

List Info

Is made up of three blocks (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.
See more

Product Modal

Displays a modal with detailed information (such as size and color) about the product the costumer wants to add to the lists they own.
See more

Autocomplete Result List

Represents the autocomplete from the search bar.
See more

Quantity Selector

Is made up of three blocks (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.
See more

Search List

Displays a search box for public lists according to the name of the owner of the list or the name of the list.
See more

Store Wallet List

Renders the virtual wallet that contains the user's credit and gift card information.
See more

Share List

Displays a button to automatically copy the URL to send the list to guests.
See more

Users List

Displays the lists the user has with their names and privacy information. It has as title and a subtitle and a link button to generate new lists.
See more

Wrappers

Are used to call the context Provider for other components and they are made of three blocks (wner-list-wrapper , guest-list-wrapper and user-lists-wrapper) and each one represents a context, which are owners, guests and users respectively.
See more

List Items Order By

Allows the user to sort the items of an list. The options for ordering are alphabetically or addition date.
See more

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:

  1. 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.
  2. 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.
  3. 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:

{"base64":"  ","img":{"width":1920,"height":1080,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":148862,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-gift-list-4.png"}}

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; }

![](https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/vtex-io/Store%20Framework%20Apps/1c3174c-image5.png", "image5.png", 1999, 1032, "#000000" ] } ] } [/block]

Email for gift purchase

If you want to send the emails that are triggered with the checkout above, you must create a new template in the admin, in the Message Center -> Templates page. The name of the template must be new-list-order and the recipient {{ownerListEmail}}.

{"base64":"  ","img":{"width":2880,"height":1468,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":410928,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-gift-list-5.png"}}
An optional HTML code for the email template can be found here.

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.

{"base64":"  ","img":{"width":1999,"height":1028,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":208249,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-gift-list-6.png"}}
If you want to have more information about a specific user, just click on the arrow next to the user's name, which will redirect you to a second screen. On this new screen, you can find information from each list of this user, including the name of the list, the value gained in the list, the date of the event, and if the event has already occurred or not.

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.

{"base64":"  ","img":{"width":1999,"height":1032,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":202344,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-gift-list-7.png"}}

Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Facebook Business Extension
« Previous
Add To Cart Button
Next »
Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
On this page