> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify Customer Data Sync

> Sync customer data from Nudj question actions to Shopify customer metafields for native segmentation and personalization

Shopify Customer Data Sync pushes user answers from Nudj question actions directly into Shopify customer metafields. This enables you to use Shopify's native customer segment builder to target customers based on their Nudj engagement data — no CSV exports, no manual data entry.

<Info>
  **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.
</Info>

## How It Works

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Segment in Shopify">
    Use Shopify's customer segment builder to create segments based on the synced metafield values. For example: "Customers where Favorite Color is Blue".
  </Step>
</Steps>

## 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.

<Tip>
  Pin fields that your support or sales team needs to see at a glance — like preference data or quiz results. Leave unpinned for fields used primarily for segmentation.
</Tip>

### 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               |

<Info>
  For boolean expansion mode, each expanded field is always created as a `boolean` type in Shopify, regardless of the parent field's data type.
</Info>

## 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`                               |

**Segment example**: `interests_sports = true AND interests_travel = true` finds customers interested in both sports and travel.

<Warning>
  Boolean expansion is limited to **5 options per action**. Each option consumes one metafield definition slot out of the 256 available per namespace. Plan your expansion fields carefully.
</Warning>

## 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.

<Tip>
  Use comma-separated mode instead of boolean expansion when you have many options or don't need per-option filtering. It uses only 1 definition regardless of option count.
</Tip>

## OAuth Scope Requirements

Shopify Customer Data Sync requires the `write_customers` scope on your Shopify app installation.

### New Installations

New Shopify app installations automatically include the `write_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's `authenticate.admin()` detects the scope difference and presents the consent screen.

<Info>
  No manual action is needed from the merchant beyond accepting the updated permissions when prompted.
</Info>

## 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                 |

<Info>
  The user's participation in the challenge is **never** blocked or affected by Shopify sync status. All sync happens asynchronously after participation is confirmed.
</Info>

## 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`                         |

These segments can then be used for targeted email campaigns, personalized storefront experiences, and marketing automation within Shopify.

## Troubleshooting

<AccordionGroup>
  <Accordion title="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_customers` scope is granted
    * Allow a few seconds for the async queue job to process
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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**
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration Guide" icon="sliders" href="/enterprise/customer-data-configuration">
    Detailed guide to all data hydration configuration options.
  </Card>

  <Card title="Overview" icon="database" href="/enterprise/customer-data-overview">
    Understand the full data hydration architecture and supported action types.
  </Card>
</CardGroup>