# Shopify Export Integration V2

This feature is in BETA version. For more information, contact your Customer Success Representative.

The Shopify Export Connector V2 is designed to create and update metafields for various Shopify resources using Shopify's GraphQL Admin API. By leveraging the more efficient and flexible GraphQL API, this version of the connector represents a significant upgrade from V1 which used REST API endpoints.

**Key capabilities**

- GraphQL API integration for improved performance and flexibility
- Support for creating and updating metafields across multiple resource types
- Batch processing capabilities
- Comprehensive error handling and validation
- Rate limiting compliance with Shopify's API guidelines


**Supported Resource Types**

The connector supports metafield operations for the following Shopify resources:

- Product
- MediaImage (replaces Product Image from V1)
- ProductVariant
- Collection
- Blog
- Page
- DraftOrder
- Customer
- Article
- Shop


## Prerequisites

- Basic knowledge of Treasure Data, including the TD Toolbelt.
- Basic knowledge of Shopify .


## Limitations & Known Issues

- MediaImage vs Product Image—A significant change from V1 to V2 is the handling of image-related metafields:
  - Whereas V1 used Product Image IDs for creating/updating metafields on product images, V2 requires MediaImage IDs.
  - MediaImage is a more versatile resource type that can reference various media types (not just product images).
  - Existing metafields created with Product Image IDs in V1 will need to be migrated to use MediaImage IDs
- Metafield keys must be 3-64 characters long
- Namespace must be 3-255 characters long


## Static IP Address of Treasure Data Integration

If your security policy requires IP whitelisting, you must add Treasure Data's IP addresses to your allowlist to ensure a successful connection.

Please find the complete list of static IP addresses, organized by region, at the following link:
[https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/](https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/)

## Use the TD Console

### Create Authentication

Your first step is to create a new authentication with a set of credentials.

1. Select **Integrations Hub**.
2. Select **Catalog**.


![](/assets/integrationshub-catalog2.e33c0a4c7d81c40cc83dd056c2143b97b1406220e213cab14ef349d69412ffef.eedebb45.png)

1. Search for your Shopify in the Catalog; hover your mouse over the icon and select **Create Authentication**.


![](/assets/shopifyi1.4f504665b75eb5d2d1b5f353f6a747aa3f7c1b5d2e55c08b2da6278ecd120a7b.eedebb45.png)![](/assets/shopifyi2.63ac6cca8a3716b1317b6e19b72e58c952551c47e5b05c6eac4063d4d346b6a2.eedebb45.png)

1. Ensure that the **Credentials** tab is selected and then enter credential information for the integration.


![](/assets/shopify2.39bc5212a8d0c245cbdc7397ee368a94fce6456486aeae4c1da24e7d2b886116.0efdb04c.png)

**New Authentication Fields**

| Parameter | Description |
|  --- | --- |
| Store name | The store identifier for your Shopify store. This can be entered in two formats: - Full store URL: for example https://*mountbaker*.myshopify.com - Store name only: for example: *mountbaker*If you’re using just the store name, it should be the unique identifier of your store without the `.myshopify.com` domain. |
| Admin API access token | The access token used to authenticate with Shopify’s Admin API. This token can be generated from your Shopify admin panel under **Apps > Develop apps > Create an app > Configure Admin API scopes**. The token needs the appropriate permissions to perform operations like managing metafields. |


1. Select **Continue**.
2. Enter a name for your authentication, and then select **Done**.


### Configure a Query Result for Export

The TD Console supports multiple ways to export data. Please follow these steps to export data from the Data Workbench.

1. Navigate to **Data Workbench** > **Queries**.
2. Select **New Query**, and define your query.
3. Select **Export Results** to configure the data exporting.
4. Select an existing Shopify CAPI authentication or create a new one described previously.
5. Configure the Export Results


![](/assets/shopify3.62b11a057d8d42a0f945a245935ed590aaa008993e28260caa65ab9fdaa3cb92.b90d17e3.png)

| Field  | Description |
|  --- | --- |
| Action | From the drop-down menu, specify the action to take:- Create metafield
- Update metafield

 |
| Resource
 | From the drop-down menu, choose the Shopify resource you want to add metafields to:
Available options:
- Product
- Media Image
- Product Variant
- Collection
- Blog
- Page
- Draft Order
- Customer
- Article
- Shop

 |
| Stop on failed record | When selected, the connector will stop processing if it encounters any errors. When unselected, it will skip failed records and continue processing the remaining records. |


1. Select **Done.**


### Detailed Guide for Create Metafield Action

For creating metafields in Shopify, you need to build a data export query that includes the necessary fields that adhere to Shopify’s guidelines. For default fields, ensure that the column names match those listed in the “Field/Column-Level Specifications” section. The connector automatically normalizes the column names to match Shopify’s required format, so you don’t need to worry about case sensitivity. For example, if a field name is “resource_id”, you can write it as “RESOURCE_ID”, “Resource_Id”, or “resource_id”, and the connector will standardize it to match Shopify’s requirements.

### Export Query Specifications

| Specification  | Description |
|  --- | --- |
| Conditionally Required Columns | Your query result must include either `resource_id` (e.g., product_id, variant_id) to identify the resource you're attaching the metafield to, along with `key`, `namespace`, and `value` columns |
| Null Value Columns | Any columns with NULL values will be ignored during the export |
| Duplicated Columns | Duplicate column names are not allowed in the export query |
| Maximum Value Length | Column values have specific length limits based on their type (detailed in the Field/Column-Level Specifications section) |


### Field/Column-Level Specifications

#### Default Field Columns

| Field | Required | Data Type | Description | Additional Specifications |
|  --- | --- | --- | --- | --- |
| resource_id | Yes | string | Identifier for the Shopify resource (product, variant, etc.) | Can be numeric ID or Global ID format. The connector will automatically handle the conversion to Global ID format if needed. |
| key | Yes | string | Unique identifier for the metafield within its namespace | - Length: 3-64 characters
- Allowed characters: alphanumeric, hyphen, underscore

 |
| namespace | Yes (Optional if using app-reserved namespace) | string | Group identifier for related metafields | - Length: 3-255 characters
- Allowed characters: alphanumeric, hyphen, underscore
- Cannot start with $

 |
| value | Yes | string | The actual content of the metafield | Always stored as a string. See the [Value Specifications by Type](/int/shopify-export-integration-v2#h5__745848692)" section below for type-specific formatting requirements for:- Basic Types (boolean, color, date, etc.)
- Reference Types (collection, product, variant references)
- List Types (arrays of the basic and reference types)

 |
| type | No | string | Defines how the value should be interpreted | If not provided, type will be automatically detected. See the [Type Detection and Specification](/int/shopify-export-integration-v2#h5__370322832)" section below. |


#### Automatic Type Detection

When you don’t include a `type` column in your query result, the connector automatically determines the metafield type based on the data type of your `value` column:

| Type  | Automatically Detected As |
|  --- | --- |
| Numbers without decimal places | `number_integer` type |
| Text values | `single_line_text_field` type |
| Numbers with decimal places | `number_decimal` type |
| Boolean values | `boolean` type |
| Other data types | converted to text and set as `single_line_text_field` type |


#### Value Specifications by Type

**Basic Types**

| Type  | Description | Validation Rules  | Examples |
|  --- | --- | --- | --- |
| boolean | True/False values | - Must be true or false
- Case-sensitive
- Max length: 65k characters

 | `true`, `false` |
| color | Color codes | - Must be valid hexadecimal color code
- Must start with #
- Must be 6 characters after #
- Max length: 65k characters

 | `"#fff123"`, `"#FF5733"` |
| date | Date values | - Must be in ISO 8601 format
- No timezone information
- Format: YYYY-MM-DD
- Max length: 65k characters

 | `"2022-02-02"` |
| date_time | Date and time values | - Must be in ISO 8601 format
- No timezone (defaults to GMT)
- Format: YYYY-MM-DDThh:mm:ss
- Max length: 65k characters

 | `"2024-01-01T12:30:00"` |
| dimension | Dimensional measurements | - Must be valid JSON object
- Must contain `value` and `unit` properties
- Value must be numeric
- Unit must be one of: in, ft, yd, mm, cm, m
- Max length: 65k characters

 | `{"value": 25.0, "unit": "cm"}` |
| json | JSON-formatted data | - Must be valid JSON data
- Can be object, array, string, number, boolean, or null
- Max length: 2M characters

 | `{"ingredient": "flour", "amount": 0.3}` |
| link | Links or references | - Must be valid JSON object
- Must contain `text` and `url` properties
- URL must be valid
- Max length: 65k characters

 | `{"text": "Learn more", "url": "https://shopify.com"}` |
| money | Monetary values | - Must be valid JSON object
- Must contain `amount` and `currency_code` properties
- Amount must be numeric string
- Currency code must match store's currency
- Max length: 65k characters

 | `{"amount": "5.99", "currency_code": "CAD"}` |
| multi_line_text_field | Multi-line text content | - Can contain multiple lines
- Max length: 65k characters

 | `"IngredientsnFlournWaternMilknEggs"` |
| number_decimal | Numbers with decimal places | - Must be in range +/-9999999999999.999999999
- Must be valid decimal number
- Max length: 65k characters

 | `"10.4"`, `"-123.456"` |
| number_integer | Whole numbers | - Must be in range +/-9,007,199,254,740,991
- Must be whole number
- Max length: 65k characters

 | `10`, `-42` |
| rating | Rating values | - Must be valid JSON object
- Must contain `value`, `scale_min`, `scale_max` properties
- Value must be within scale range
- Scale values must be numeric
- Max length: 65k characters

 | `{"value": "3.5", "scale_min": "1.0", "scale_max": "5.0"}` |
| rich_text_field | Formatted text content | - Must be valid JSON object
- Must be valid rich text JSON structure
- Must contain `type` and `children` properties
- Max length: 65k characters

 | `{"type": "root", "children": [{"type": "paragraph", "children": [{"type": "text", "value": "Bold text.", "bold": true}]}]}` |
| single_line_text_field | Single-line text content | - Single line only (no newlines)
- Max length: 65k characters

 | `"VIP shipping method"` |
| url | Web URLs | - Must be valid URL format
- Must use allowed schemes: https, http, mailto, sms, tel
- Max length: 2,048 characters

 | `"https://www.shopify.com"` |
| volume | Volume measurements | - Must be valid JSON object
- Must contain `value` and `unit` properties
- Value must be numeric
- Unit must be one of: ml, cl, l, m3, us_fl_oz, us_pt, us_qt, us_gal, imp_fl_oz, imp_pt, imp_qt, imp_gal
- Max length: 65k characters

 | `{"value": 20.0, "unit": "ml"}` |
| weight | Weight measurements | - Must be valid JSON object
- Must contain `value` and `unit` properties
- Value must be numeric
- Unit must be one of: oz, lb, g, kg
- Max length: 65k characters

 | `{"value": 2.5, "unit": "kg"}` |


**Reference Types**

| Type | Description | Validation Rules | Examples |
|  --- | --- | --- | --- |
| collection_reference | Reference to a collection | - Must be valid Shopify Global ID format - Format: gid://shopify/Collection/{id} | `"gid://shopify/Collection/1"` |
| file_reference | Reference to a media file | - Must be valid Shopify Global ID format - Format: gid://shopify/MediaImage/{id} | `"gid://shopify/MediaImage/123"` |
| metaobject_reference | Reference to a metaobject | - Must be valid Shopify Global ID format - Format: gid://shopify/Metaobject/{id} - Must match specified metaobject definition | `"gid://shopify/Metaobject/123"` |
| mixed_reference | Reference to a metaobject | - Must be valid Shopify Global ID format - Format: gid://shopify/Metaobject/{id} | `"gid://shopify/Metaobject/123"` |
| page_reference | Reference to a page | - Must be valid Shopify Global ID format - Format: gid://shopify/Page/{id} | `"gid://shopify/Page/1"` |
| product_reference | Reference to a product | - Must be valid Shopify Global ID format - Format: gid://shopify/Product/{id} | `"gid://shopify/Product/1"` |
| variant_reference | Reference to a product variant | - Must be valid Shopify Global ID format - Format: gid://shopify/ProductVariant/{id} | `"gid://shopify/ProductVariant/1"` |


**List Types**

List types support arrays of basic types and reference types. List types are prefixed with list., and all list types support their base type’s validation rules applied to each array element. The examples below show common list types.

Note:

| Type | Description | Validation Rules | Examples |
|  --- | --- | --- | --- |
| list.collection_reference | Array of collection references | - Must be array of valid collection references - Each item must follow collection_reference rules | `["gid://shopify/Collection/1", "gid://shopify/Collection/2"]` |
| list.color | Array of color codes | - Must be array of valid color codes - Each item must follow color rules | `["#FFF123", "#E6E6FA"]` |
| list.date | Array of dates | - Must be array of valid dates - Each item must follow date rules | `["2022-01-01", "2022-05-05"]` |
| list.date_time | Array of timestamps | - Must be array of valid timestamps - Each item must follow date_time rules | `["2024-01-01T12:30:00", "2024-05-01T12:30:00"]` |
| list.dimension | Array of dimension objects | - Must be array of valid JSON objects - Each item must follow dimension rules | `[{"value": 25.0, "unit": "cm"}, {"value": 35.0, "unit": "cm"}]` |
| list.number_integer | Array of integers | - Must be array of valid integers - Each item must follow number_integer rules | `[10, 20, 30]` |
| list.number_decimal | Array of decimals | - Must be array of valid decimals - Each item must follow number_decimal rules | `["10.4", "20.5", "30.6"]` |
| list.single_line_text_field | Array of text strings | - Must be array of strings - Each item must follow single_line_text_field rules | `["VIP shipping method", "Standard shipping method"]` |
| list.url | Array of URLs | - Must be array of valid URLs - Each item must follow url rules | `["https://www.shopify.com", "https://www.shopify.dev"]` |


### Detailed Guide for Update Metafield Actions

To update existing metafields in Shopify, you need to build a data export query that includes the necessary fields. The connector automatically handles the data validation and formatting requirements for each field.

**Export Query Specifications**

| Specification  | Description |
|  --- | --- |
| **Required Columns** | Your query result must include a `metafield_id` and `value` columns. |
| **Optional Columns** | You can include `key`, `namespace`, and `type` columns if you want to validate the metafield information before an update. |
| **Null Value Columns** | Any columns with NULL values will be ignored during the export. |
| **Duplicated Columns** | Duplicate column names are not allowed in the export query. |


#### Required Columns

| Field  | Data Type  | Description  | Validation Rules  | Notes  |
|  --- | --- | --- | --- | --- |
| metafield_id | string | Identifier for the existing metafield | Must be a valid existing metafield ID | - This can be numeric ID or Global ID format (e.g., gid://shopify/MetaField/123). - The connector will automatically handle the conversion to Global ID format if needed.

 |
| value | string | New value for the metafield | - Always stored as string regardless of type - Must comply with the metafield's type validation rules

 | - See "Value Specifications by Type" section in Create Metafield documentation for type-specific requirements.

 |


#### Optional Columns

These fields are not required for updates but can be included for validation purposes:

| Field  | Data Type  | Description  | Validation Rules  | Notes  |
|  --- | --- | --- | --- | --- |
| key | string | Identifier for the metafield within its namespace | - Length: 3-64 characters - Allowed characters: alphanumeric, hyphen, underscore

 | If provided, the connector will verify this matches the existing metafield before update. |
| namespace | string | Group identifier for related metafields | - Length: 3-255 characters - Allowed characters: alphanumeric, hyphen, underscore - Cannot start with $

 | If provided, the connector will verify this matches the existing metafield before update. |
| type | string | Defines how the value should be interpreted | Must be one of supported types (see Create Metafield documentation) | If provided, the connector will verify this matches the existing metafield before update. |


### (Optional) Schedule Query Export Jobs

You can use Scheduled Jobs with Result Export to periodically write the output result to a target destination that you specify.

Treasure Data's scheduler feature supports periodic query execution to achieve high availability.

When two specifications provide conflicting schedule specifications, the specification requesting to execute more often is followed while the other schedule specification is ignored.

For example, if the cron schedule is `'0 0 1 * 1'`, then the 'day of month' specification and 'day of week' are discordant because the former specification requires it to run every first day of each month at midnight (00:00), while the latter specification requires it to run every Monday at midnight (00:00). The latter specification is followed.

#### Scheduling your Job Using TD Console

1. Navigate to **Data Workbench > Queries**
2. Create a new query or select an existing query.
3. Next to **Schedule**, select None.
![](/assets/image2021-1-15_17-28-51.f1b242f6ecc7666a0097fdf37edd1682786ec11ef80eff68c66f091bc405c371.0f87d8d4.png)
4. In the drop-down, select one of the following schedule options:
![](/assets/image2021-1-15_17-29-47.45289a1c99256f125f4d887e501e204ed61f02223fde0927af5f425a89ace0c0.0f87d8d4.png)
| Drop-down Value | Description |
|  --- | --- |
| Custom cron... | Review [Custom cron... details](#custom-cron-details). |
| @daily (midnight) | Run once a day at midnight (00:00 am) in the specified time zone. |
| @hourly (:00) | Run every hour at 00 minutes. |
| None | No schedule. |


#### Custom cron... Details

![](/assets/image2021-1-15_17-30-23.0f94a8aa5f75ea03e3fec0c25b0640cd59ee48d1804a83701e5f2372deae466c.0f87d8d4.png)

| **Cron Value** | **Description** |
|  --- | --- |
| `0 * * * *` | Run once an hour. |
| `0 0 * * *` | Run once a day at midnight. |
| `0 0 1 * *` | Run once a month at midnight on the morning of the first day of the month. |
| "" | Create a job that has no scheduled run time. |



```
 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)
```

The following named entries can be used:

- Day of Week: sun, mon, tue, wed, thu, fri, sat.
- Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec.


A single space is required between each field. The values for each field can be composed of:

| Field Value | Example | Example Description |
|  --- | --- | --- |
| A single value, within the limits displayed above for each field. |  |  |
| A wildcard `'*'` to indicate no restriction based on the field. | `'0 0 1 * *'` | Configures the schedule to run at midnight (00:00) on the first day of each month. |
| A range `'2-5'`, indicating the range of accepted values for the field. | `'0 0 1-10 * *'` | Configures the schedule to run at midnight (00:00) on the first 10 days of each month. |
| A list of comma-separated values `'2,3,4,5'`, indicating the list of accepted values for the field. | `0 0 1,11,21 * *'` | Configures the schedule to run at midnight (00:00) every 1st, 11th, and 21st day of each month. |
| A periodicity indicator `'*/5'` to express how often based on the field's valid range of values a schedule is allowed to run. | `'30 */2 1 * *'` | Configures the schedule to run on the 1st of every month, every 2 hours starting at 00:30. `'0 0 */5 * *'` configures the schedule to run at midnight (00:00) every 5 days starting on the 5th of each month. |
| A comma-separated list of any of the above except the `'*'` wildcard is also supported `'2,*/5,8-10'`. | `'0 0 5,*/10,25 * *'` | Configures the schedule to run at midnight (00:00) every 5th, 10th, 20th, and 25th day of each month. |


1. (Optional) You can delay the start time of a query by enabling the Delay execution.


### Execute the Query

Save the query with a name and run, or just run the query. Upon successful completion of the query, the query result is automatically exported to the specified destination.

Scheduled jobs that continuously fail due to configuration errors may be disabled on the system side after several notifications.

(Optional) You can delay the start time of a query by enabling the Delay execution.

## Activate a Segment in Audience Studio

You can also send segment data to the target platform by creating an activation in the Audience Studio.

1. Navigate to **Audience Studio**.
2. Select a parent segment.
3. Open the target segment, right-mouse click, and then select **Create Activation.**
4. In the **Details** panel, enter an Activation name and configure the activation according to the previous section on Configuration Parameters.
5. Customize the activation output in the **Output Mapping** panel.


![](/assets/ouput.b2c7f1d909c4f98ed10f5300df858a4b19f71a3b0834df952f5fb24018a5ea78.8ebdf569.png)

- Attribute Columns
  - Select **Export All Columns** to export all columns without making any changes.
  - Select **+ Add Columns** to add specific columns for the export. The Output Column Name pre-populates with the same Source column name. You can update the Output Column Name. Continue to select **+ Add Columns**to add new columns for your activation output.
- String Builder
  - **+ Add string** to create strings for export. Select from the following values:
    - String: Choose any value; use text to create a custom value.
    - Timestamp: The date and time of the export.
    - Segment Id: The segment ID number.
    - Segment Name: The segment name.
    - Audience Id: The parent segment number.


1. Set a **Schedule**.


![](/assets/snippet-output-connector-on-audience-studio-2024-08-28.a99525173709da1eb537f839019fa7876ffae95045154c8f2941b030022f792c.8ebdf569.png)

- Select the values to define your schedule and optionally include email notifications.


1. Select **Create**.


If you need to create an activation for a batch journey, review [Creating a Batch Journey Activation](/products/customer-data-platform/journey-orchestration/batch/creating-a-batch-journey-activation).

## (Optional) Export Integration Using the CLI

You can also use CLI (Toolbelt) to export results to Shopify by specifying the information you want to export to your Shopify server using the --result option of the td query command. For more information about the td query command, refer to [TD Toolbelt: Query Commands](https://api-docs.treasuredata.com/en/tools/cli/api/#query-commands).

Options for the .yml configuration files used for TD Toolbelt are formatted in JSON, and the general structure is as follows.

- For create metafields



```yaml
out:
  type: 'shopify_v2'
  admin_api_access_token: {admin_api_access_token}
  store_name: {store_name}
  action: 'create'
  resource: 'product'
  stop_on_failed_record: false
```

- For update metafields



```yaml
out:
  type: 'shopify_v2'
  admin_api_access_token: {admin_api_access_token}
  store_name: {store_name}
  action: 'update'
  stop_on_failed_record: false
```

**Parameters**

| Name | Description | Value | Default Value | Required |
|  --- | --- | --- | --- | --- |
| type | Connector type | shopify_v2 | N/A | Yes |
| admin_api_access_token | A Master API key to authenticate your export from TD | N/A | N/A | Yes |
| store_name | Shopify store name | N/A | N/A | Yes |
| action | Operation on Shopify metafields | Supported values:- Create
- Update

 | Create | Yes |
| resource | The object the metafields should create | Supported values:- article
- blog
- collection
- customer
- draft_order
- media_image
- page
- product
- product_variant
- order
- shop

 | Shop | Yes if action is create |
| stop_on_failed_record | Stop the job if record invalid data | True or False | False | N/A |


### CLI Usage Example

**Create Metafields**


```bash
td query --result '{"type":"shopify_v2","admin_api_access_token":"admin_api_access_token","store_name":"store_name","action":"create,"resource":"shop", "stop_on_failed_record":true}' -d sample_database "select shop_id,key,namespace,value from tbl_shop" -T presto
```

**Update Metafields**


```bash
td query --result '{"type":"shopify_v2","admin_api_access_token":"admin_api_access_token","store_name":"store_name","action":"update, "stop_on_failed_record":true}'  -d sample_database "select metafield_id,value from tbl_metafield" -T presto
```

## See Also

- The Result Export can be scheduled to periodically upload data to a target destination. See [Scheduling Jobs Using TD Console](https://docs.treasuredata.com/smart/project-product-documentation/scheduling-jobs-using-td-console).
- All import and export integrations can be added to a [TD Workflow](https://docs.treasuredata.com/articles/pd/about-treasure-workflow). The td>: data operator can export a query result to a specified integration. For more information, see [Reference for Treasure Workflow Operators](https://docs.treasuredata.com/articles/pd/reference-for-treasure-data-operators/a/h1_76525622).