Skip to content
English
More support
Merchant Dashboard
  • There are no suggestions because the search field is empty.

How to use Custom Event Mapping

By default, Instant AI uses Shopify's standard product fields (price, image, name, description) in every email. For most stores, that's exactly right and you don't need to do anything.

Custom Event Mapping is for stores where Shopify's defaults don't tell the full story. You tell Instant which custom data to use for a given piece of product info, and from then on every email shows that custom data instead of the Shopify default. For example, if you map your member pricing, every email shows the member price instead of the public catalog price. Set it up once and it applies everywhere.

Should you use it?

Use Custom Event Mapping if:

  • You sell personalised or custom products (mugs, prints, canvases, jewellery) where the standard product image is a generic mockup and the real product image lives somewhere else
  • You run member, club, or wholesale pricing that differs from the public Shopify price
  • You have email-specific creative, like a lifestyle shot stored in a metafield rather than the catalog primary image
  • You have alternative product names or descriptions stored in metafields that you'd rather use in emails
  • You store rich product data in JSON metafields (e.g. pricing objects from an external system) and want to pull a specific value from it

You don't need it if your standard Shopify product fields already show what you want shoppers to see in emails. There's nothing to set up and Instant will work as it always has.

 

Where to find it

Go to Configuration > Email Settings > Event Mapping.

Create a mapping

There are four steps in the setup wizard.


1. Choose field

Select the standard Shopify field you want to replace. The available fields are:

  • Price {price}
  • Compare at price {compareAtPrice}
  • Primary image {primaryImage}
  • Name {name}
  • Description {description}

 

2. Pick your source

Choose where Instant should pull the replacement data from. Today the only source is Product metafield.

You'll need to enter:

  • Property Namespace: the namespace of your Shopify metafield (e.g. Club Price)
  • Property Key: the key of the metafield (e.g. price_something)
  • Type: select Single value for plain values, or JSON if your metafield stores structured JSON data

If you select JSON, a JSON path field appears. Use dot notation to point to the value you want. For example, use amount for {"amount":"89.0"}, or price.amount for {"price":{"amount":"89.0"}}.

 

3. Set the fallback rule

Choose what should happen if a product doesn't have the metafield, or the metafield is empty:

  • Use the default Shopify value: Instant will render the standard Shopify field as normal, exactly as if no mapping existed.
  • Suppress the field: Instant will leave the field blank with no default or placeholder.

 

4. Confirm

Give the mapping a name (e.g. "Club Price") and review the summary. You'll see the field you're replacing, the data source, the fallback behaviour, and which flows it applies to.

Click Confirm to save.

 

Manage your mappings

Saved mappings appear in the Mappings table on the Event Mapping tab.

  • Status: use the toggle to turn a mapping on or off without deleting it. New mappings start in the off state, so flip the toggle on when you're ready for the mapping to apply to live emails.
  • Edit: click the actions menu (⋯) and select Edit mapping to update any step.
  • Delete: click the actions menu (⋯) and select Delete to remove the mapping permanently.
Changes apply as soon as a mapping is live. There's no need to republish flows or campaigns.

FAQ

Where does the metafield data come from? Instant pulls metafields directly from Shopify. Make sure your metafield is exposed to the Storefront API and has values populated on the products you want the mapping to apply to.

Which emails does a mapping apply to? All flows. Once a mapping is turned on, the replaced field uses your custom data everywhere it appears in flow emails.

What happens if a single product is missing the metafield? The fallback rule you set in step 3 takes over for that product only. Other products with the metafield populated will continue to use the mapped value.

Can I have multiple mappings on the same field? No. Each Shopify field (e.g. {price}) can only have one active mapping at a time. If you want to change the mapping on a field, edit the existing one or delete it and create a new one.

What happens if I delete a mapping? The standard Shopify field returns to being used in emails immediately. Deleting can't be undone, so if you only want to pause a mapping use the status toggle instead.