Objective

This document outlines the integration of Terrific with VTEX. We use the latest version of the REST API available as of today (June 27, 2025) as our reference.

The implementation is divided into two main components to ensure a complete and seamless integration:

Back-to-Back Integration: This part manages product synchronization and cart connectivity, ensuring that product data and user interactions are accurately reflected between systems.
Front-End Module Integration: The approach depends on the VTEX technology used on the site. Implementation details vary between Legacy VTEX and VTEX IO, adapting to the specific front-end environment of each platform.

API

VTEX allows you to generate API Key and Access Token for authentication.
Steps to generate:

Go to your VTEX admin.
Go to Account Setting section.
Select API Keys
Click to Generate Key
Include a Key identification like a Terrific Integration
If no custom roles exist, an API Key with Owner-level access should be created. It’s recommended to set up a role with permissions for: Catalog API, Checkout API, Pricing, and Logistics.
Copy and share the generated keys.
Important: the generated token is displayed only once, so make sure to copy and save it immediately.

More details

You can view the attached video (VTEX integration).

Embedding

In this section we explain how to embed Terrific’s scripts to access the functionalities of Live Shopping, Time Line, Shoppable Videos and any new Terrific components.

VTEX has two main versions:

VTEX Legacy: This is the older platform version, based on a traditional CMS. Stores are primarily built with HTML, CSS, and JavaScript, managed through templates and files in the Portal CMS.
VTEX IO: Is VTEX’s low-code, serverless platform for building customized stores and applications. It uses a modern environment based on React and Node.js, enabling continuous deployments, native integration with VTEX services, and a modular architecture.
It is ideal for creating dynamic frontend experiences, custom integrations, and new touchpoints without compromising performance.

VTEX Legacy

Embedding the scripts and tags required for Terrific’s modules to work is straightforward, as it involves directly updating the site templates through VTEX’s admin CMS:

1. Log in to your VTEX Admin.

2. Go to CMS > Portal > Templates.

3. Identify the base template used by most pages, usually named template-base.html or similar.

4. Edit the base template and insert the Terrific script inside the <head> tags:

<script defer src="https://terrific.live/terrific-sdk.js" storeId="{store_id}"></script>

5. Locate the section where you want to embed the content (e.g., home, product page, etc.).

6. Use a Custom HTML module.

7. Paste the embed tag:

<div data-source="terrific" embedding-id="{terrific-embedding-id}"></div>

VTEX IO

To work with VTEX IO, you need to install and use VTEX CLI, a command-line tool that lets you interact with your store, build projects, test in workspaces, deploy, and more.

Here you can find the detailed guide to install the VTEX IO CLI.

We'll use 2 Storefront applications based on the app boilerplates published by VTEX in their public GitHub repository:

To embed the Terrific script in the global site header
To embed any Terrific component (Live Shopping, Timeline, etc.) into any section of the site (homepage, catalog, etc.)

Using VTEX IO CLI

Once the VTEX IO CLI is installed, you’re able to create or edit applications using the VTEX IO CLI, you first need access to a development environment (a VTEX store) and authenticate with the following command:

vtex login {accountName}

Now, you must now select or create a workspace where you will test and validate the integration.

vtex use {workspaceName}

If you enter a workspace name that doesn’t exist, the VTEX CLI IO will ask if you want to create it.

Once you're in the desired workspace, you can start making integration and test them directly within that environment.

You can find a detailed guide on how to use the VTEX IO CLI and its available commands here.

Add Terrific Script

To add the Terrific script inside the <head> across the entire site, We will use an App that is already configured to insert the required script.
You can download the project from here.

Set up the component in the store

To enable the use of this component in your store-theme, follow these steps:

1. Run vtex link inside the component project.

2. Reference the new component in the manifest.json file of the store-theme project.

Note: The namespace of your component in the manifest (for both projects) must match the namespace used in your store.

3. Run vtex link again, now in the store-theme project.

This process ensures that all scripts defined in the component’s head.html file are automatically included in the store.

IMPORTANT: Make sure to deploy both projects (Terrific Script and store-theme) in the same workspace.

Once the component is installed in your workspace, you will see the “Terrific Global Script” app under the My Apps section in the VTEX admin panel.

Click on the app and enter your Store ID, which will be provided by the Terrific team during the onboarding process.

Add Terrific Tag Embed

To add a Terrific tag that embeds a module like Live Shopping, Timeline, etc, We will use an App that is already configured to insert the required script.
You can download the project from here.

Set up the component in the store

To enable the use of this component in your store-theme, follow these steps:

1. Run vtex link inside the component project.

2. Reference the new component in the manifest.json file of the store-theme project.

Note: The namespace of your component in the manifest (for both projects) must match the namespace used in your store.

3. Run vtex link again, now in the store-theme project.

IMPORTANT: Make sure to deploy both projects (Terrific Tag Embed and store-theme) in the same workspace.

How to use it

Just like the Pixel app, this application enables a block in the admin to set a default global embed ID.

However, you can override the embed ID for each individual block. This allows you to reuse the same component to embed different elements across the site.
Here’s an example of how to embed the Live Shopping popup on the Homepage: