Skip to main content
The Voyado Customer Engagement app for Shopify lets you map customer metafields from Shopify to custom attributes in Voyado Customer Engagement. This means data you already store on a customer’s Shopify profile, like loyalty tier, preferred size, or a referral source, can flow straight into Voyado and power your segmentation, personalization, and automation. Some of the most common fields are mapped for you automatically, and you can add your own mappings for anything else you track in Shopify metafields.

​
How it works

The attribute mapping page distinguishes between two kinds of mappings:
  • Locked mappings. A set of default mappings that come pre-configured and can’t be changed. These cover the core customer fields Voyado needs, like name, address, and email.
  • Custom mappings. Mappings you configure yourself, between any Shopify customer metafield and any custom attribute on your Voyado contact type.
Voyado Customer Engagement is the source of truth for attribute definitions, including the allowed values for Dropdown and Checkbox Multiple attributes. Every time you open the mapping page, we fetch the current attributes, types, and allowed values directly from Voyado, so what you see is always up to date.

​
Locked mappings

The following Shopify fields are always mapped to their corresponding Voyado attribute. You’ll see these listed under Locked Mappings on the mapping page, marked with a lock icon. They’re not available to select when you create a custom mapping. All metafields the app creates for these locked mappings live under the voyado namespace (for example, voyado.discoveryKey). Note that the Shopify metafield key and the Customer Engagement attribute name are not always identical — the birthday metafield is voyado.birthDay, while the Customer Engagement attribute it fills is birthdate.
Shopify field names are given here in their REST form (first_name, default_address.zip). The same fields appear in their GraphQL form (firstName, defaultAddress.zip) in Field mappings, which documents the full receipt and order payloads alongside contact data.

​
Supported attribute types

When you create a custom mapping, only Voyado attribute types that are compatible with the selected Shopify metafield type are shown. Here’s how types line up:

​
Create a custom mapping

1

Open Attribute Mapping

Go to App Settings > Attribute Mapping in the Voyado Customer Engagement app in Shopify.
2

Add a mapping

In the Custom Mappings section, select Add mapping.
3

Select the Shopify metafield

Search for and select the metafield you want to sync. You can select metafields from any namespace, including ones created by other apps.
4

Select the Voyado attribute

Choose the attribute you want to map to. Only attributes compatible with your selected metafield’s type are shown.
5

Check type compatibility

A green checkmark means you’re good to go. If you see a warning, the types aren’t compatible — choose a different attribute or metafield.
6

Resolve value alignment (if applicable)

If you mapped a Dropdown or Checkbox Multiple attribute and the allowed values don’t match between Shopify and Voyado, review the side-by-side comparison and confirm that we can update the Shopify values to match Voyado.
7

Create the metafield (if it doesn't exist yet)

Choose whether to create it under the voyado namespace, or skip creation and save the mapping as inactive until you create it yourself.
8

Save

Leave the Enabled toggle on, then select Save.

​
Creating a new metafield manually

If the metafield you want doesn’t exist in Shopify yet and you’d rather create it yourself first:
1

Create the definition in Shopify

Go to Settings > Metafields and metaobjects > Customers > Add definition.
2

Save it

Create and save the metafield.
3

Complete the mapping

Go back to Attribute Mapping in the Voyado Customer Engagement app and complete your mapping.

​
How syncing works

Once a mapping is active, it’s applied automatically. Here’s what triggers a sync: This applies whether the sync happens in real time through webhooks, or as part of a bulk import (for example, during onboarding or a manual re-sync). Both use whatever mapping configuration is active at the time.

​
Good to know

Here are some important points to know when working with metafields:
  • Mapping is one-to-one which means that a metafield can only be mapped to one Voyado attribute, and an attribute can only be the target of one mapping. This also means the same field cannot be mapped twice.
  • A Shopify metafield with no value does not overwrite an existing value in Voyado. An empty source field never deletes existing data.
  • If a mapped Voyado attribute is later deleted in Customer Engagement, or a mapped Shopify metafield definition is removed, the mapping will be flagged as “Broken” the next time you open the field mapping section.
  • For Dropdown attributes, if an incoming value during sync doesn’t match any allowed value in Voyado, that update is skipped and a warning is written to the sync log rather than the sync failing outright.
  • Any metafield the app creates on your behalf is always placed under the voyado namespace. This keeps app-managed fields collision-free and easy to identify, and means they can be cleanly removed if you ever uninstall the app. If you already store similar data under custom or another namespace, you’ll need to map those fields manually; the app doesn’t auto-detect or migrate any existing data for you.
  • Per-mapping behavior for null or empty values isn’t configurable yet. Support for that is planned for a future release.
Syncing currently only goes one way, from Shopify to Voyado. Changes you make to an attribute directly in Voyado Customer Engagement are not pushed back to Shopify.

​
Exclude orders from syncing

Merchants (or other Shopify apps) can exclude individual orders from syncing to Voyado Customer Engagement. The exclusion holds for as long as the metafield is set, and can be reversed by clearing it. This is controlled by a dedicated metafield on the Shopify order.
This is separate from customer attribute mapping above. It applies to the order resource, not the customer resource, and isn’t part of the mapping configuration.
When the exclusion metafield is present and set to true on an order, the Voyado Customer Engagement app skips that order in every sync operation, no matter how many times it’s subsequently updated.

​
The exclusion metafield

The Voyado Customer Engagement app never sets this metafield itself. It’s up to you, or another app, to apply it to orders that should be excluded.

​
What gets excluded

​
How exclusion and correction work

The exclusion check runs on every event tied to an order, including creation, updates, fulfillment, and cancellation. The app reads the current value of voyado.exclude_from_sync at the time of each event and acts on it directly; it isn’t cached or treated as a permanent state.
If you set the metafield by mistake, just set it back to false (or remove it) and trigger a re-sync, either by updating the order in Shopify or running a manual re-sync in the app.

​
Sync coverage

The exclusion check applies across every sync mechanism, with no exceptions.
For the bulk import job, voyado.exclude_from_sync isn’t included in the standard order export payload. It has to be fetched explicitly alongside order data from the Shopify Admin API.

​
Logging

Every time an order event comes in and the order is excluded, we log:
  • Order ID
  • Event type that triggered the check (for example, order/updated or order/paid)
  • Reason: excluded via voyado.exclude_from_sync
  • Timestamp
Excluded orders aren’t surfaced as errors anywhere in the app. They’re silent from your perspective and logged only for internal debugging.