Map Value Action

Look a key up in a JSON map and store the found value in a variable. Use it to turn a ZIP code, a customer tier or any other value into a status that later blocks can act on.

Overview

The Map value action looks a key up in a JSON object and stores the value it finds in a variable. Conditions and blocks later in the flow read that variable like any other value.

Use this action to:

  • Turn the delivery ZIP code into a region status (WAITLIST, PRESALE, ACTIVE) and block or allow products by that status
  • Map a customer tier to a discount percentage
  • Map a province or country code to a shipping zone
  • Keep the lookup table in a metafield that Shopify Flow or another app updates, so the function does not change when the table changes
A validation flow: the Map value block turns the delivery ZIP code into a region status, a condition checks the status, and Fail validation blocks the checkout

Available for Function Types

  • Validation
  • Payment Customization
  • Discount

Setup

Add the action

Click Add Action and select Map value

Name the variable

Enter the name that later blocks use to read the found value

Set the key

Enter the value to look up, or link it to an input field, a variable, a metafield or an attribute

Set the map

Link a JSON metafield or a JSON attribute, or enter the JSON object as text

Select the key match

Keep Exact, or select Prefix when the key can be longer than the map keys

Add a fallback

Turn on the default value if no map key can match

Use the result

Refer to the variable in conditions or in expressions on later blocks

The Map value panel: variable name, Key linked to ZIP Code, Map linked to a shop metafield, Key match set to Prefix, default value UNKNOWN

Settings

Variable name

Required

The internal name that identifies this variable. Use lower case letters and no spaces.

Warning

Give each variable a different name. A second action with the same name replaces the first value.

Key

Required

The value to look up in the map. Enter a static text, or link the key to an input field (for example the ZIP code of the delivery address), an upstream variable, a metafield, an attribute, or an advanced expression.

Map

Required

A JSON object. Each key of the object maps to a value:

{"12345": "WAITLIST", "94105": "ACTIVE"}

Link a JSON metafield or a JSON attribute, or enter the JSON object as text. The action reads the whole JSON object. A metafield that another app, such as Shopify Flow, keeps up to date lets you change the map without a change to the function.

Note

A function cannot read a metafield value that is larger than 10,000 bytes. Keep the map smaller than this limit.

Key match

Optional

  • Exact (default) — the map key must be equal to the key
  • Prefix — the map key matches when the key starts with it. When more than one map key matches, the longest map key wins

With Prefix, a map of 5-digit ZIP codes also serves ZIP+4 codes: the map key 12345 matches the ZIP code 12345-6789.

Default value

Optional

Turn this on to store a value when no map key matches, or when the key or the map is empty. Without a default value the variable is empty, and a condition on an empty variable is false.

Default value type

The type of the fallback value. Select String, Integer, or Decimal.

Default value

The fallback value to store. Leave it empty for the default of the type, which is 0 for numbers and empty text for a string.


How It Works

The block runs one time per function run, before the blocks that follow it:

  1. It reads the key: the linked field, variable, metafield, attribute or expression, or the static text
  2. It reads the map as one JSON object
  3. With Exact, it takes the value whose key is equal to the key. With Prefix, it takes the value of the longest map key that the key starts with
  4. It stores the found value in the variable. A string value stays a string, a number stays a number
  5. When nothing matches, it stores the default value, or leaves the variable empty

The flow editor shows the block as a pipeline: the key, the map it looks the key up in, and the variable it stores the value as.

The Map value block on the canvas: ZIP Code, look up in custom.region_status_by_zip with Prefix, store as region_status or UNKNOWN when no match

Examples

Region status from the delivery ZIP (Validation)

You keep the status of each delivery region in a shop metafield of the JSON type, and you want to block checkout for regions on the waitlist.

Add the action

Add a Map value action with the variable name region_status

Link the Key to the ZIP Code of the delivery address

Link the Map to the shop metafield with the value {"12345": "WAITLIST", "94105": "ACTIVE"}

Match by prefix

Select Prefix as the key match, so that 12345-6789 also finds 12345

Set the fallback

Turn on the default value and enter UNKNOWN, so a ZIP code that is not in the map is blocked too

Block the checkout

Add a condition region_status is one of WAITLIST, UNKNOWN, and connect a Fail validation action to its Then branch

Result

A buyer with the ZIP code 12345-6789 gets WAITLIST and the checkout is blocked. A buyer with 94105 gets ACTIVE and the checkout continues

Discount percentage by customer tier (Discount)

A customer metafield holds the tier, and a JSON map turns the tier into a percentage.

Add the action

Add a Map value action with the variable name tier_pct

Link the Key to the customer metafield that holds the tier, for example gold

Enter the map

Enter the map as text: {"gold": 20, "silver": 10}

Set the fallback

Turn on the default value, select Integer and leave the value empty, so customers without a tier get 0

Use the value

In the discount block, link the discount value to the variable tier_pct

Result

Gold customers get 20% off, silver customers 10%, and everyone else no discount


Important Considerations

Note

A linked key or map needs a function input that reads the delivery address and the metafield together. The editor picks that input for you when you save. A shop metafield in the same function as the delivery address needs the Advanced plan.

Tip

Test the block with the Cart Tester: set a delivery address with the ZIP code and a sample value for the shop metafield, then run the function to see the stored value and the result of the conditions.


Troubleshooting

The variable is always the default value

  • Check that the map is a JSON object, with the keys and the text values in double quotes. The panel shows an error under the Map field when the text is not valid JSON
  • Check the key match: with Exact, the key 12345-6789 does not find the map key 12345. Select Prefix
  • Check that the linked metafield has a value on the shop, product or customer the function reads

The condition after the block never matches

  • A condition on an empty variable is false. Turn on the default value so the variable always holds a value you can test for
  • Compare text values with Is one of or Equals and numbers with the number operators. The found JSON value keeps its type