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 Engage 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 Engage attribute name are not always identical — the birthday metafield is voyado.birthDay, while the Engage 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 Engage 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 Engage 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
If a Shopify metafield has no value for a customer, we don’t overwrite the existing value in Voyado. An empty source field never blanks out existing data.
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 existing data.Per-mapping behavior for null or empty values isn’t configurable yet. Support for that is planned for a future release.
Exclude orders from syncing
Merchants (or other Shopify apps) can exclude individual orders from syncing to Voyado Engage. 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.
true on an order, the Voyado Engage app skips that order in every sync operation, no matter how many times it’s subsequently updated.
The exclusion metafield
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 ofvoyado.exclude_from_sync at the time of each event and acts on it directly; it isn’t cached or treated as a permanent state.
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/updatedororder/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.