PIM to VTEX integration: how to import and synchronise product data

How do you integrate a PIM with VTEX? First decide which system owns which data: the PIM owns product content, the ERP owns prices and stock, and VTEX runs sales. Then map the PIM data model to the VTEX catalogue and create the structure in VTEX: categories, brands, specification groups and fields. Only then send products, SKUs, images and trade policy assignments through the Catalog API. Prices and stock from the ERP go separately, through the Pricing API and the Logistics API. Finally, run change synchronisation with a queue, retries and an error report.

Below we describe each step based on the VTEX documentation (as of 24 October 2026). If you are still checking whether VTEX fits your company, start with our page VTEX: what it is and how to feed it product data. This article is for teams that have chosen VTEX and are planning the connection to their PIM.

Who owns what: ERP, PIM and VTEX

An integration stays stable when every piece of information has one owner. If a description can be changed both in the PIM and in the VTEX admin, after a few weeks nobody knows which version is true.

• ERP: item codes and EANs, prices, stock levels, B2B customers. It sends prices and stock to VTEX and receives orders from VTEX.
• PIM: names, descriptions, technical attributes, variants, images, documents, translations and category assignment. It sends the catalogue to VTEX.
• VTEX: the shop category tree, trade policies, promotions, search, cart and orders.

The shop category tree does not have to copy the PIM tree. The VTEX documentation openly assumes that a structure from an ERP or PIM may not suit an online shop. In that case we keep a separate tree for the VTEX channel in the PIM, or a category mapping table. A practical rule: fields that come from the PIM are not edited in the VTEX admin, because the next synchronisation overwrites them anyway.

How the VTEX catalogue is built

• Categories usually have three levels: departments, categories and subcategories. A brand is mandatory and must exist before the product.
• A product has at least one SKU (variant) and is assigned to a brand and to the most specific category.
• Specifications have three layers: groups, fields and values. A field has one of eight types (including text, number, combo, radio, checkbox and indexed text); combo, radio and checkbox need a list of values. Groups and fields belong to a category and also apply to all of its subcategories.
• SKU specifications tell variants apart (for example size) and can only be combo or radio.
• Images are assigned to an SKU as the URL of a publicly readable image.
• A trade policy (called a sales channel in the API) decides in which channel a product is visible, with which prices and logistics.

Mapping PIM concepts to VTEX

PIM terms depend on the system: Akeneo has families and product models, Ergonode has templates, and Pimcore has object classes. The table shows how we translate them to VTEX.

PIM to VTEX integration step by step

The order follows the dependencies in the VTEX catalogue: you cannot assign a product to a brand that does not exist, or a specification to a field that has not been created.

1. Agree the identifiers. The linking key is usually the product code from the ERP, stored in VTEX as RefId. When a product is created, VTEX returns its own ID; VTEX recommends saving it, so we keep it in the PIM and later updates hit the same record.
2. Create the category tree: departments first, then categories, then subcategories.
3. Create the brands.
4. Create the specification groups, from departments down. Groups in a parent category pass to all its subcategories, so a field that not every subcategory uses should not sit in the parent's group.
5. Create specification fields and their values, then activate the fields. Inactive fields do not work.
6. Send the products with category and brand, then the product specifications.
7. Assign products to a trade policy. Every product must be in the main trade policy (ID 1) to be visible in the shop. Further policies make products available to marketplaces, for example.
8. Send the SKUs with RefId or EAN, then the SKU specifications. Do not create an SKU as active; VTEX recommends turning on ActivateIfPossible, so the SKU activates itself once it meets the conditions.
9. Add images to the SKUs. Without an image an SKU does not activate.
10. Send prices and stock from the ERP. Pricing API: a base price for every SKU, optionally a list price and fixed prices for price tables. Logistics API: warehouses first, then the stock of each SKU in each warehouse.
11. Send translations if the shop runs in several languages.
12. Turn on change synchronisation (described below).

Variants, languages and trade policies

Variants

A variant axis from the PIM becomes a combo or radio SKU specification in VTEX. The VTEX documentation warns that SKU specifications are mandatory: if you add a new SKU specification to a category, every SKU in that category must have it. That is why we fix the variant axes before the first import, not during it.

Languages

VTEX support turns on the multi-language catalogue on request. Translations are sent through the catalogue multi-language API, separately for each locale: names, descriptions, keywords and URLs of products, categories and brands, SKU names, and specification names and values. Once this is on, catalogue translations cannot also be managed through GraphQL. When a translation is missing, VTEX Intelligent Search shows the content in the shop's default language, so we check translation completeness in the PIM before a product reaches the channel. According to the documentation, FastStore support is in closed beta.

Trade policies

A trade policy sets the assortment, prices and logistics for a sales channel. Its equivalent in the PIM is the channel: we keep a list of channels where a product may be sold in the PIM and assign the product to VTEX policies from it. Different prices for another policy are set in the Pricing API as fixed prices for a price table.

Change synchronisation and error handling

The first import happens once; synchronisation runs for years. Our rules:

• Send only changes. The PIM knows what changed: Akeneo has the Event Platform, Pimcore exposes data through Datahub, and Ergonode through its GraphQL API.
• A queue instead of direct calls. The default Catalog API limit is 45,000 requests per minute per account and 15,000 per minute per endpoint. The Pricing API accepts 2,000 writes per minute (33 per second, with a burst allowance of 500 requests). Above the limit VTEX returns error 429. VTEX then recommends increasing pauses between retries (exponential backoff) and a queue, and the Pricing API returns a Retry-After header with the number of seconds to wait.
• A timeout is not a failure. The VTEX import guide says a timeout is expected in the process and integration code should plan for retries. Before retrying, we check whether the product was created after all, so we do not duplicate it.
• A report of what failed and why (for example an SKU without an image or a missing specification value) goes back to the PIM, to the person who can fix the data.
• A check in the other direction. VTEX notifies about SKU changes (price, stock, data, activation) through an affiliate endpoint or the Broadcaster app in VTEX IO. That is how we confirm an SKU really activated.

Migrating a large catalogue to VTEX

• Spreadsheets only for corrections. The VTEX spreadsheet import takes up to 10,000 rows per file, and the export covers up to 300,000 products. The template must not be changed, and only a spreadsheet exported with all fields can be imported. For a lasting integration and large catalogues we use the API.
• A technical category. When the target category tree is not ready, VTEX suggests an inactive technical category (called "Integration" in the documentation) that receives all products, which are then moved to the right categories. A technical brand works the same way.
• A pilot on one category. Before sending the whole catalogue, we run a full cycle on one category: product, SKU, image, price, stock and visibility in the shop. Then we send the rest in batches.
• Data moves once, into the PIM. When moving from Magento, Shopware or a custom shop, we clean the data in the PIM and publish it from there to VTEX. The next change of shop platform then does not mean another product data migration.

We do not use the separate Seller Portal Catalog API for the main integration: according to VTEX it is in beta, may be withdrawn and is limited to 100,000 products per account.

Common pitfalls

1. An SKU without an image, or without RefId and EAN, stays inactive. The PIM should block publishing such a variant.
2. A specification group in a different category than the product. The API returns 200 OK, but the specification is visible neither in the admin nor in the shop.
3. A field in a parent category appears in every subcategory, and a new SKU specification is required from every SKU in the category.
4. No main trade policy: the product is not visible. To be visible, an SKU also needs a price in the policy and stock.
5. Translations from two sources: the multi-language API and GraphQL translations do not work together.
6. Manual edits in the VTEX admin to fields from the PIM disappear at the next synchronisation.

Pimcore, Akeneo, Ergonode and VTEX: ready-made connector or API?

We found no ready-made connectors between Pimcore, Akeneo or Ergonode and VTEX, so we build the integration through the API. On 24 October 2026 we checked the VTEX App Store (no results for Akeneo, Pimcore, Ergonode or "PIM"), the Akeneo App Store (no results for "VTEX") and GitHub. Integration platforms (iPaaS) such as Alumio describe a VTEX and Akeneo connection within their own platform; that is an option for companies that already use one.

On the VTEX side the integration uses the Catalog API, the Pricing API and the Logistics API. On the PIM side: Datahub in Pimcore, the REST API and the Event Platform in Akeneo, and the GraphQL API in Ergonode. Which PIM to choose depends on the catalogue and the team, not on the shop platform. See our PIM implementation page and the pages on Pimcore, Akeneo and Ergonode.

How we work at LemonMind

We have worked on product data and integrations since 2010, with 70+ PIM and e-commerce projects and a team of 30+ specialists in Gdańsk. We are a Pimcore Platinum Partner and an Ergonode partner, and we also implement Akeneo.

When a company moves to VTEX, we take the part that decides catalogue quality: the data model, mapping attributes to categories and specifications, the catalogue migration, and the PIM and ERP integration with VTEX, including error reporting. If the problem is supplier files in many formats, openProd helps: our separate AI platform that imports supplier files into the catalogue.