Shopify

Sync customer data from your warehouse to Shopify. Keep your Shopify customer records, tags, and marketing consent enriched with the latest data from your data warehouse using the Shopify Admin GraphQL API.

Prerequisites

• A Shopify store (Basic, Shopify, Advanced, or Plus plan)
• A custom app created in the Shopify admin with the Admin API access token
• The custom app must have the following API access scopes:
  • read_customers and write_customers

Authentication

Admin API Access Token

1. In your Shopify admin, go to Settings > Apps and sales channels > Develop apps
2. Click Create an app and give it a name (e.g., “Zeotap Integration”)
3. Click Configure Admin API scopes
4. Select read_customers and write_customers scopes
5. Click Save, then click Install app
6. Copy the Admin API access token (starts with shpat_...)
7. Paste the token into the Admin API Access Token field in Zeotap

Important: The access token is only shown once. Store it securely. If you lose it, you must uninstall and reinstall the app to generate a new token.

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Audience sync modes use Shopify customer tags. The tags field in your mapping is used as the tag to add or remove from customers.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

How It Works

1. Customer Sync: Zeotap sends individual GraphQL mutations (customerCreate, customerUpdate) for each row. For upsert mode, Zeotap first searches for an existing customer by the configured identifier (email or phone), then creates or updates accordingly.

2. Audience Sync (Tags): For audience membership, Zeotap uses the tagsAdd and tagsRemove GraphQL mutations. Map a tags field in your field mapping containing the tag value to add or remove from customers.

3. Marketing Consent: The accepts_email_marketing and accepts_sms_marketing fields are automatically mapped to Shopify’s marketing consent objects (emailMarketingConsent and smsMarketingConsent).

4. Error Handling: Each row is processed individually. Failed rows are reported with specific error messages from the Shopify API. Transient errors (rate limits, server errors) are retried with exponential backoff.

Rate Limits

Shopify’s GraphQL Admin API uses a cost-based rate limiting system:

Each customer mutation costs approximately 10 points. Zeotap automatically handles rate limiting with exponential backoff and respects the Retry-After header.

Best Practices

• Use email as the identifier for upsert mode to match existing customers reliably
• Map only the fields you need to minimize API cost per mutation
• Use audience sync (tags) to manage customer segments in Shopify without overwriting other customer data
• Schedule syncs during off-peak hours if you are on a Standard plan to avoid rate limit contention with other apps
• Use E.164 format for phone numbers (e.g., +14155551234) to ensure proper matching

Troubleshooting

Authentication failed: invalid or expired access token

Verify the Admin API access token in your Shopify app settings. If the app was uninstalled and reinstalled, the old token is no longer valid. Generate a new token by reinstalling the app.

Store not found

Verify the store domain is correct and includes .myshopify.com (e.g., my-store.myshopify.com). The domain must be the Shopify-assigned domain, not a custom domain.

Customer not found for update

When using update mode, the primary key must be a valid Shopify customer ID. For upsert mode, ensure the identifier field (email or phone) is mapped and contains valid values.

No tags found in row for audience sync

Audience sync modes require a tags field in your field mapping. Map a source column containing the tag value to the tags destination field.

Rate limiting (429 errors)

Zeotap automatically retries rate-limited requests with exponential backoff. If you see persistent rate limit errors, consider reducing sync frequency or upgrading your Shopify plan for higher rate limits.

Insufficient API scopes

If mutations fail with permission errors, verify your custom app has read_customers and write_customers scopes enabled. After updating scopes, you must reinstall the app.

Marketing consent not updating

Shopify requires specific consent state values. Ensure the accepts_email_marketing and accepts_sms_marketing fields contain boolean values (true/false, 1/0, or yes/no).

Duplicate customer created instead of updated

This can happen if the identifier field (email or phone) in the source data does not exactly match the existing customer record in Shopify. Verify the identifier values are clean and consistently formatted.