VTEX connector
The VTEX Connector connects your VTEX store to Constructor, enabling automatic synchronization of your catalog data — including categories, brands, products, SKUs, and specifications — to power AI-driven search and product discovery.
Why use it?
VTEX stores manage rich, hierarchical catalogs with deep category trees, brand associations, multi-SKU products, and detailed specifications. The VTEX Connector accelerates the path to value by bridging this complex catalog model directly into Constructor's AI platform. Instead of building and maintaining a custom integration, you install a lightweight app, enter your VTEX API credentials, and Constructor handles the rest — reading your full catalog and mapping it into the data structures that power personalized search, browse, recommendations, and more.
How it works
The VTEX Connector is a lightweight VTEX IO service app. After installation, you save your VTEX API credentials (App Key and App Token) in the app's settings screen. The app then notifies Constructor that your store is ready for catalog synchronization. Constructor uses the provided credentials to read your catalog data via the VTEX Catalog API.
The connector is read-only — it never writes to or modifies any data in your VTEX store.
Features
- Full catalog sync — Categories, brands, products, SKUs, and specifications are all synchronized to Constructor.
- Read-only connection — Constructor only reads your catalog; no data in your store is ever modified.
- One-time setup — Install the app and enter your VTEX App Key and Token. That's it.
- Hierarchical category trees — VTEX category hierarchies are mapped to Constructor
item_groups, preserving parent-child relationships. - Brands as first-class entities — Brand data is synced and available for faceting, filtering, and merchandising.
- SKU-level attributes — Specifications, dimensions, images, prices, and other SKU-level data are mapped to Constructor variation-level fields.
Installation
Prerequisites
- A VTEX store with an active account.
- A Constructor.io account. Contact us if you don't have one.
- A VTEX App Key and App Token with Catalog read permissions.
Step 1 — Install the app
Install the Constructor Connect App from the VTEX App Store, or via the VTEX CLI:
vtex install constructoriopartner.constructor-connectStep 2 — Open app settings
In the VTEX Admin, navigate to Apps > My Apps > Constructor Connect App and click Settings.
Step 3 — Enter your VTEX credentials
Fill in the two required fields:
| Field | Description |
|---|---|
| VTEX App Key | Your VTEX API Key for authentication. |
| VTEX App Token | Your VTEX API Token. Keep this value secret. |
A note on credentials
Security note: Your credentials are transmitted securely via HTTPS and are used exclusively by Constructor to read your catalog. They are never logged or stored by the connector app itself.
Permissions: The App Key/Token pair must have read access to the VTEX Catalog API. We recommend creating a dedicated credential pair with the minimum required permissions.
Step 4 — Save
Click Save. This triggers a secure notification to Constructor with your store details and credentials, and catalog synchronization begins automatically.
You're all set!
Once saved, Constructor will begin reading and indexing your catalog. You can update your credentials at any time by returning to the settings screen and saving again — each save triggers a fresh notification to Constructor.
Data mapping
Constructor's data model organizes catalog data into three core levels:
| Constructor concept | Description |
|---|---|
item_groups | Logical groupings such as categories or product families. |
items | Individual products. |
variations | Purchasable variants of a product (sizes, colors, etc.). |
The sections below describe how each VTEX catalog entity maps into this model.
Categories
VTEX Categories are mapped to Constructor item_groups, preserving the full hierarchical tree structure.
| VTEX field | Description | Constructor mapping |
|---|---|---|
Id | Unique category identifier | item_group ID |
Name | Category display name | item_group name |
FatherCategoryId | Parent category ID (null for root) | Parent item_group reference |
Title | SEO title | item_group metadata |
Description | Category description | item_group metadata |
Keywords | Associated keywords | item_group metadata |
IsActive | Whether the category is active | Used to filter synced categories |
Brands
VTEX Brands are mapped as Constructor item_groups metadata and are available as facets for filtering and merchandising.
| VTEX field | Description | Constructor mapping |
|---|---|---|
Id | Unique brand identifier | Facet / metadata ID |
Name | Brand display name | Facet value and metadata |
IsActive | Whether the brand is active | Used to filter synced brands |
Title | SEO title | Metadata |
MetaTagDescription | Brand description | Metadata |
Product level
VTEX Products are mapped to Constructor items.
| VTEX field | Description | Constructor mapping |
|---|---|---|
ProductId | Unique product identifier | item ID |
ProductName | Product display name | item name |
BrandName | Associated brand | item facet / metadata |
CategoryId | Primary category ID | item_group association |
DepartmentId | Top-level department ID | item_group association |
Description | Product description | item description |
DescriptionShort | Short description | item metadata |
LinkId | URL-friendly slug | item URL / metadata |
KeyWords | Search keywords | item keywords |
IsVisible | Visibility flag | Used to filter synced products |
IsActive | Active flag | Used to filter synced products |
ReleaseDate | Product release date | item metadata |
SKU level
VTEX SKUs — the purchasable units — are mapped to Constructor variations.
| VTEX field | Description | Constructor mapping |
|---|---|---|
Id | Unique SKU identifier | variation ID |
ProductId | Parent product ID | Parent item reference |
NameComplete | Full SKU name (product + variation) | variation name |
IsActive | Active flag | Used to filter synced variations |
ListPrice | Original / list price | variation price metadata |
Price | Current selling price | variation price metadata |
AvailableQuantity | Stock availability | variation inventory metadata |
Images | SKU image URLs | variation images |
Height | Package height | variation metadata |
Width | Package width | variation metadata |
Length | Package length | variation metadata |
WeightKg | Package weight | variation metadata |
EAN | Barcode / EAN | variation metadata |
RefId | Reference / manufacturer code | variation metadata |
UnitMultiplier | Unit multiplier for sales | variation metadata |
Specifications (product and SKU attributes)
VTEX Specifications — custom attributes defined at both the product and SKU level — are mapped to Constructor facets and metadata.
| VTEX field | Description | Constructor mapping |
|---|---|---|
Name | Specification name (e.g., "Color", "Material") | Facet key or metadata key |
Value | Specification value(s) | Facet value(s) or metadata value(s) |
FieldGroupName | Specification group | Used for organizational context |
IsFilter | Whether the spec is filterable in VTEX | If true, mapped as a Constructor facet; otherwise as metadata |
Position | Display order | Metadata |
A note on product data
Facets vs. metadata: Specifications marked as filterable (
IsFilter: true) in VTEX are mapped to Constructor facets, making them available for search filtering and refinement. Non-filterable specifications are stored as metadata for display and merchandising purposes.Product vs. SKU specifications: Product-level specifications are mapped at the
itemlevel in Constructor. SKU-level specifications are mapped at thevariationlevel, enabling fine-grained filtering by variant attributes such as size or color.
Updated about 2 hours ago