The VTEX connection enriches or creates BlueConic® profiles with data from VTEX orders. When you authenticate the connection, VTEX automatically creates an Orders Event Feed that the connection listens to in order to capture and process new or updated orders. This connection supports scheduled batch import.
Important:
The VTEX Event Feed does not support historical orders. To import historical order data, use an alternative ingestion path such as the SFTP connection. The feed only provides new or updated orders from the feed that is created.
This integration supports incremental updates only and is not designed for extremely high–volume order ingestion.
Connection details
Goal types: Import
Frequency: Batch (scheduled or manual)
Before you begin
Before setting up the VTEX connection, confirm the following:
Your VTEX account is active.
You have access to VTEX Admin settings.
You have permission to create and manage Application Keys in VTEX.
The Application Key you use has the following permissions:
Orders: Read
Orders Feed: Read
Any BlueConic profile properties needed to store incoming order or customer data are created in advance.
Create a VTEX connection
Select Connections in the BlueConic navigation bar.
Click Add connection.
In the modal that appears, search and select the VTEX connection.
Enter the name and metadata details for the connection.
Click Save.
Authenticate
On the Set up and run locate the setup section.
Enter your Account name.
Enter your Application key.
Generate an external system application key in VTEX.
You can manage your application keys via Admin > Account Settings > Application Keys.
Only users with the required VTEX roles can create application keys.
Enter the Application token associated with the application key.
Click Save.
Note: VTEX automatically creates an Orders API Event Feed when you create an Application Key with Orders: Read permissions. Each Application Key is linked to a single feed and cannot be reused across connections, tenants, or applications, because feed messages are consumed once and cannot be replayed. VTEX removes feed data after 4–14 days of inactivity, depending on configuration. When a feed is removed, all associated events are permanently deleted.
Configure the import
Generate the import goal
Select the Import orders data into BlueConic goal.
Optional: Edit the goal name to clearly describe the import purpose.
Click away from the name field to save your changes.
1. (Optional) Process your data before import
Select and search for a Data Processor that can perform various functions, such as transformation, filtering, manipulation, and more, to ensure that BlueConic exports the data correctly.
2. Link identifiers between VTEX and BlueConic
Select the VTEX identifier used to identify customers or orders.
Select the matching BlueConic profile property.
Optional: Select Allow creation of new profiles in BlueConic to create a profile when no existing match is found.
3. (Optional) Map VTEX data to BlueConic
Click Add mapping.
Select a VTEX field from the left column.
Select the BlueConic profile property to store the value.
(Optional) select a merge rule to control how values are written (for example, set or clear).
Repeat these steps to map additional fields.
(Optional) click Add all detected fields to automatically create mappings for all detected VTEX fields
4. (Optional) Import Timeline events into BlueConic
Click Import data into BlueConic events.
Select a Timeline event type from the dropdown, or create a custom timeline event type.
Map a VTEX field to the Event ID to uniquely identify each event.
Map a VTEX field to the Event date / time to determine when the event occurred.
(Optional) click Add mapping to map additional VTEX fields to timeline event properties.
Repeat mappings as needed.
Run the connection
Activate the goal
Check the goal to activate it.
The green arrow indicates the active direction for the connection.
Run Manually
To run the connection:
Turn the connection On.
Click Save.
On the Set up and run page, scroll to the Run history section.
Click Run now to run all activated goals in the connection manually.
The run appears at the top of the table.
Run on a Schedule
Click the Settings icon.
Choose an option from the drop-down list to configure by:
Number of times per day
Days of the week
Days of the month
Weekday of the month
Select the time of day if required.
Click OK.
Click Save.
Note: At default, the feed is processed every 3 minutes and is running via the express lane, so it is near real-time. However you can update the scheduling settings to support your own use cases.
Troubleshoot the VTEX connection
Event feed not generating or updating
Go to VTEX Admin > Account Settings > Application Keys.
Confirm the Application Key used in BlueConic has the following permissions:
Orders: Read
Orders Feed: Read
Regenerate the Application Token in VTEX and update it in BlueConic.
Save the connection settings and retry running the connection.
Orders not appearing in BlueConic
Check the following:
The Event Feed URL is valid:
https://{{accountName}}.vtexcommercestable.com.br/api/orders/feedThe application key has not expired.
The connection runs every 3 minutes.
Order statuses included match your filtering configuration.
The Import events from date setting is not set to a future date.
Feed stuck on old orders
VTEX tracks feed consumption using a cursor.
Fix:
Reset the Orders Feed cursor in VTEX (if available).
Clear Import events from date in BlueConic and run the connection again.
Next steps
Use VTEX order data to build segments and trigger personalization.