Prerequisite: Your community must have a linked Shopify store with the
write_customers OAuth scope. Existing Shopify installations are automatically prompted for re-consent when the scope is added.How It Works
Admin Configures Hydration
On a question action, enable data hydration and configure the Shopify sync section. Nudj automatically creates the metafield definition on your Shopify store.
User Answers the Question
When a user completes the action, Nudj stores the answer locally and queues an async job to sync it to Shopify.
Metafield is Written
The queue job writes the resolved value to the customer’s metafield in Shopify using the
$app:nudj namespace. If the customer doesn’t exist in Shopify (no externalUserId), the sync is silently skipped.Shopify-Specific Configuration
When Shopify sync is enabled on a data hydration config, additional settings become available:Pin to Customer Detail
When enabled, the metafield appears directly on the customer detail page in your Shopify admin. This makes the data immediately visible when viewing a customer profile.Display Name and Description
These values appear in the Shopify admin when viewing metafield definitions. Use clear, descriptive names so your Shopify team understands what each field represents.- Display Name: Shown as the field label (e.g., “Favorite Color”)
- Description: Shown as help text (e.g., “Answer from the Style Quiz challenge”)
Type Mapping
Nudj data types map to Shopify metafield types automatically:| Nudj Type | Shopify Metafield Type | Notes |
|---|---|---|
| Text | single_line_text_field | Standard text metafield |
| Integer | number_integer | Whole numbers |
| Decimal | number_decimal | Decimal numbers (JSON format) |
| Boolean | boolean | True/false values |
| Date | date | ISO date string |
For boolean expansion mode, each expanded field is always created as a
boolean type in Shopify, regardless of the parent field’s data type.Metafield Namespace
All Nudj-synced metafields use the$app:nudj namespace. This is a Shopify app-reserved namespace that:
- Prevents naming conflicts with other apps or custom metafields
- Groups all Nudj data together in the Shopify admin
- Is automatically associated with your Shopify app installation
Boolean Expansion in Shopify
Boolean expansion is particularly powerful with Shopify because Shopify’s customer segment builder supports boolean filters natively. Example: A “Pick your interests” question with options: Sports, Music, Travel, Food, Tech This creates 5 metafield definitions:| Metafield Key | Type | Value (user selected Sports + Travel) |
|---|---|---|
interests_sports | boolean | true |
interests_music | boolean | false |
interests_travel | boolean | true |
interests_food | boolean | false |
interests_tech | boolean | false |
interests_sports = true AND interests_travel = true finds customers interested in both sports and travel.
Capacity Management
Shopify allows a maximum of 256 custom metafield definitions per namespace per resource type. Nudj checks this limit before creating new definitions.How Definitions Are Counted
| Config | Definitions Used |
|---|---|
| Standard field (Text, Integer, etc.) | 1 |
| Comma Separated multi-select | 1 |
| Boolean Expansion (3 options) | 3 |
| Boolean Expansion (5 options) | 5 |
Approaching the Limit
The admin panel warns when you’re approaching the 256-definition limit. New configurations that would exceed the limit are rejected at save time with a clear error message.OAuth Scope Requirements
Shopify Customer Data Sync requires thewrite_customers scope on your Shopify app installation.
New Installations
New Shopify app installations automatically include thewrite_customers scope. No additional setup is needed.
Existing Installations
Existing installations are prompted for re-consent automatically. When a merchant next accesses the Nudj Shopify app, Shopify’sauthenticate.admin() detects the scope difference and presents the consent screen.
No manual action is needed from the merchant beyond accepting the updated permissions when prompted.
Error Handling and Retries
Shopify sync is designed to be resilient:| Scenario | Behavior |
|---|---|
| Shopify API temporarily unavailable | Job retried automatically (up to 5 times with backoff) |
Customer has no externalUserId | Sync silently skipped — data still stored in Nudj |
| Community has no Shopify credentials | Sync silently skipped |
| Rate limit exceeded | Job retried after backoff |
| Invalid metafield value | Marked as failed, not retried |
| Type coercion failed | Nudj data stored, Shopify sync skipped |
The user’s participation in the challenge is never blocked or affected by Shopify sync status. All sync happens asynchronously after participation is confirmed.
Segmentation Examples
Once data is synced, use Shopify’s customer segment builder:| Use Case | Segment Query |
|---|---|
| Customers who prefer blue | favorite_color = 'Blue' |
| Customers who rated 4+ stars | product_rating >= 4 |
| Customers interested in sports | interests_sports = true |
| Customers with a birthday in March | customer.metafields.app_nudj.birthday.month = 3 |
| Customers who answered the quiz | quiz_answer IS NOT NULL |
Troubleshooting
Metafield not appearing on customer
Metafield not appearing on customer
- Verify the user has an
externalUserId(linked Shopify customer) - Check that the community has active Shopify credentials
- Ensure the
write_customersscope is granted - Allow a few seconds for the async queue job to process
Definition not created in Shopify
Definition not created in Shopify
- Check that you saved the action after enabling data hydration
- Verify the field key doesn’t conflict with an existing definition of a different type
- Check the 256-definition capacity limit
- The definition sync job runs asynchronously — allow a few seconds
Pin to customer detail not showing
Pin to customer detail not showing
- Ensure Pin to Customer Detail is enabled in the hydration config
- The pin setting can be updated even after first sync
- Verify the metafield definition exists in Shopify admin under Settings > Custom data > Customers
Boolean expansion fields missing
Boolean expansion fields missing
- Check that the question has 5 or fewer options
- Verify sufficient definition capacity (each option = 1 definition)
- Ensure no other action uses the same field key with a different mode
Next Steps
Configuration Guide
Detailed guide to all data hydration configuration options.
Overview
Understand the full data hydration architecture and supported action types.