The Shopify – NetSuite integration app supports all Shopify metafield types. The app passes the NetSuite metafield value directly to Shopify's API without any internal transformation or validation. This means:
- Every metafield type (single line text, list, boolean, reference, date, rating, etc.) is supported.
- The app does not modify or reformat values — it sends whatever is stored in NetSuite as-is.
- Ensure that NetSuite values are formatted exactly as Shopify expects, because any format mismatch can cause the metafield update to fail or be rejected by Shopify.
Prerequisite: A metafield definition must exist in Shopify for the resource type (Product, Variant, Customer, etc.) before the integration can sync values to it. The app does not automatically create definitions.
For an example of mapping single-line text list-type metafields, see Mapping single-line text list-type metafields (Connective).
Complete these steps once per metafield before enabling the sync.
- In Shopify Admin, go to Settings > Custom data. Select the resource type, for example, Products or Variants.
- Click Add definition. Give it a name and set the Namespace and Key. For example, namespace custom, key listmeta. The namespace and key together uniquely identify the metafield and must match what you configure in the integration app.
- Choose the data type that matches what you will be sending from NetSuite. See Formatting by metafield type below. Categories and validation rules are optional; the integration app does not require them.
-
Click Save. Shopify will now accept values for this metafield via the API.
Note
Creating a metafield definition only defines the structure and type of the metafield in Shopify. The actual metafield values are created later when they are manually entered in Shopify or synced through the integration app.
Once the Shopify definition exists and the NetSuite field holds the correctly formatted value, you need to wire them together in the NetSuite item to Shopify product (add or update) flow's field mapping.
In the integration app mapping editor, each Shopify metafield is identified by its namespace and key using the following pattern:
Shopify definition |
Integration app destination field key |
Namespace: custom, Key: listmeta |
metafields.custom.listmeta |
Namespace: my_fields, Key: fabric |
metafields.my_fields.fabric |
Namespace: global, Key: country_of_origin |
metafields.global.country_of_origin |
Important
- The namespace and key must match exactly The metafields.namespace.key value in the integration app must match the namespace and key of the definition you created in Shopify exactly, including case. A mismatch means the metafield will not be updated, and no error may be surfaced in the flow run, making this one of the harder issues to diagnose.
- Check the Sync Shopify metafield definitions setting to import Shopify product and variant metafield definitions into the integration app. After adding or updating metafield definitions in Shopify, select this option and click Save in Settings > General to sync metafields with the correct metafield type. If metafield definitions do not exist in Shopify, the item or matrix item flow assigns a default type based on the metafield value, such as single_line_text_field, number_integer, number_decimal, boolean, JSON, or date. For more information, see Manage metafield definitions for Shopify products and their variants.
The NetSuite field that holds the metafield value must contain a plain string formatted exactly as Shopify expects for that type. The integration app sends the value as-is; it does not convert or wrap the value in any way.
Send the value as a plain string. No special formatting required. For example:
NetSuite field value |
Result in Shopify |
Made from 100% organic cotton |
Stored as a single-line text metafield value on the product. |
Send the value as a JSON array of strings, quoted items separated by commas, enclosed in square brackets, with no extra spaces inside the brackets. For example:
NetSuite field value |
Notes |
["ttest","custom field","test121"] |
A list with three text items, in exact format confirmed during testing. |
["Red","Blue","Green"] |
A list of colour option strings. |
- ttest,custom field,test121: comma-separated without array brackets
- [ "ttest", "custom field" ]: extra spaces inside brackets
- ttest|custom field|test121: pipe-separated string
Reference-type metafields require the Shopify Global ID (GID) of the referenced record and not the numeric ID or record name. The GID is a full URI in the format gid://shopify/<ResourceType>/<NumericID>.
Reference type |
Required format |
Customer |
gid://shopify/Customer/123456789 |
Product |
gid://shopify/Product/987654321 |
Collection |
gid://shopify/Collection/112233445 |
When you run the NetSuite item to Shopify product (add or update) flow:
- Reads the metafield value from the NetSuite source field.
- Maps it to the destination field metafields.namespace.key in the integration app import.
- Passes the value directly to Shopify without reformatting or validation
-
Shopify validates the value against the type defined in the metafield definition. If the format is wrong, Shopify rejects it.
Note
Multiple metafields in one flow. You can map multiple metafields in the same flow run by adding additional destination field mappings, each using its own metafields.namespace.key path. Each mapping is independent; a failed value on one metafield does not block the others from syncing.
Before configuring the value in NetSuite, use this method to confirm the exact format Shopify expects for any metafield type. This is the recommended verification step for all customers before going live.
- Create a metafield definition in Shopify using the same namespace, key, and type as the metafield you intend to sync from NetSuite.
- Enter a sample value on a product: Open any product in Shopify Admin and manually type a representative sample value into the metafield. Save the product.
-
Check the raw value via /metafields.json:In your browser, navigate to: https://your-store.myshopify.com/products/[product-handle]/metafields.json
This returns the raw JSON for all metafields on that product. Find your entry by namespace and key, and look at the value field. The string you see is the exact format you must store in NetSuite.
-
Use that format in NetSuite: Store the value in the corresponding NetSuite field in the exact format observed in the JSON response. The integration will send it to Shopify unchanged.
Tip
For other resource types. The same approach works for customer or variant metafields. For customers, use the Shopify Admin API: /admin/customers/[customer-id]/metafields.json. Once you have confirmed the format, update the integration app mapping as described in Configure the Metafield Mapping.
Shopify metafield type |
Required format in NetSuite |
Example |
Single line text |
Plain string |
Organic cotton |
Multi-line text |
Plain string with actual newline characters (not \n escape sequences) |
A NetSuite long-text field containing multiple lines of text |
List of single-line text |
JSON array of strings |
["ttest","custom field","test121"] |
Integer / Decimal number |
Numeric string |
42 or 3.14 |
True/False (Boolean) |
Lowercase string |
true or false |
Date |
ISO 8601 date string |
2026-05-11 |
Date and time |
ISO 8601 datetime string, no timezone suffix |
2026-05-11T10:00:00 |
Product / Customer / Collection reference |
Shopify GID string |
gid://shopify/Customer/123456789 |
When in doubt, check /metafields.json: For any type not listed above, always use the test-field verification method in Verify the correct format using a test metafield. Create the metafield in Shopify, enter a sample value manually, and read back the exact format from /metafields.json. That value is the ground truth for what NetSuite must send.