# Shopify Integration

> For Ptengine tag installation in Shopify, see also [Installing Tags in Shopify](https://helps.ptengine.com/en/getting-started/othertag/tag-shopify).

## Shopify Integration Setup Guide

### Opening Shopify App Settings

Follow these steps to set up the Shopify integration:

1. Log in and access the relevant account
2. Under the Experience module, click the "Settings" icon to the right of the profile list, then click "External App Integration" and select Shopify
3. Click Shopify to proceed with the setup

## Creating a Custom App in Shopify

First, you need to create a Shopify custom app to receive data from Ptengine. This process takes less than 5 minutes and requires no technical skills (though you need the appropriate permissions in Shopify). This custom app will only operate within the authorized scope and poses no risk to your store's performance or customer experience.

Creating a custom app involves four steps:

[Step 1: Create the App](https://www.notion.so/a8b8195c81704357932ed4d32ba1017d?pvs=21)

[Step 2: **Configure App Permissions**](https://www.notion.so/8af46c23bc9f42399e3108b954ff1761?pvs=21)

[Step 3: **Install the App**](https://www.notion.so/62ebc700562d46098964267354b8727b?pvs=21)

[Step 4: Obtain the Token](https://www.notion.so/f917794c13354adfbb775258071e7dab?pvs=21)

### Step 1: Create the App

1. Go to the Shopify store admin page and click Settings in the bottom left corner
2. Click Apps and Sales Channels
3. Click Develop Apps for Your Store
4. Click Allow Custom App Development
5. After allowing, the following page will appear. Click Create an App.
6. Fill in the required information and click Create (choose your own app name)
7. Reaching the following page indicates the app was created successfully

### Step 2: **Configure App Permissions**

1. A newly created app has no permissions. To integrate webhooks, you need to configure API permissions. Click Configure Admin API Scopes.
2. This shows all admin permission toggles for the app
3. Find and check the following permissions
4. Click Save

### Step 3: **Install the App**

1. After configuring permissions, click API Credentials
2. Click Install App and confirm the installation

### Step 4: Obtain the Token

1. After installation, click Reveal Token Once

   (**The token can only be viewed once.** Please store it securely. After clicking to reveal the token, if you do not save it manually, do not refresh or navigate away from the page, as you will not be able to view it again.)
2. After saving the API token, go to Ptengine to continue creating the Shopify connection

## Creating a Shopify Connection

### Creating a Shopify Connection

1. In the Shopify management interface, click "Create Connection" in Step 2
2. Enter the required information on the settings screen

**Connection Name**

Give this connection a name for easy identification in future use.

**Shopify Store Name**

Note: **This is your store's registration name in Shopify, not the display name shown in the store.**

You can usually find it in the URL after logging into the Shopify admin panel.

or

**Shopify Custom App Token**

Paste the token obtained in [Step 4: Obtain the Token](https://www.notion.so/f917794c13354adfbb775258071e7dab?pvs=21) here.

3. After filling in all information, click "Start Verification"
4. Once verification succeeds, the connection can be saved.

If you need to push different form results to different store customer lists, you can create multiple connections here.

#### Common Connection Errors:

Error message as shown above:

Error case 1: The Shopify store name is incorrect.

Error case 2: The corresponding Shopify store token is incorrect. (Note: The token is only displayed once when generated in the Shopify admin. Afterward, it is always shown in an encrypted state. Make sure to save it separately.)

### Editing a Shopify Connection

Click the Edit button in the list to modify a Shopify connection.

The editing process is the same as the creation process.

If your Shopify settings have changed (e.g., a token reset), you can enter the updated information here.

Connections previously configured in an Experience will continue to work after modification.

### Deleting a Shopify Connection

Click the Delete button in the list to delete a Shopify connection.

Note: Deletions cannot be undone. Before deleting, please carefully confirm that the connection will no longer be needed and will not affect any Experiences using this connection for data push.

When deleting, we will check for running or scheduled Experiences. If there are no related Experiences, you can delete directly. If there are running or scheduled Experiences, you must check the "Confirm" checkbox before proceeding with the deletion.

After deletion, all data pushes will stop immediately.

However, the Experience itself will continue to run, and form data collection within Ptengine will not be affected.

## Setting Up Shopify Push for an Experience

### Entering Push Settings

Follow these steps to complete the Shopify push settings within an Experience.

\*This setting only applies to Experiences that contain forms. If you cannot see the related options, please create a form first.

1. Click Experience Edit
2. Go to the "Automation" module and click "Edit"

   (Currently, "Automation" only provides form result push functionality. You need to create a form in the Experience first before this module becomes visible. More automation capabilities will be added to this module in the future. We welcome your feedback on data push, automated actions, and other automation-related needs.)

### Configuring Push Rules

1. Select "Push results to Shopify"
2. From the previously created connections, select the connection to use
3. After selecting a connection, Ptengine will parse all form fields used in the Experience

* For Email-type fields, Ptengine will automatically detect and map them
* For other field types, if you need to push them, you must manually add and specify their mapping to target fields. For example:
* About Shopify Required Fields
  * Shopify uses the "Email" field as the unique identifier, so when pushing data, there must be a field that maps to Shopify Email.
  * If you have created multiple test variations or devices, each variation and device form must have a field that maps to Shopify Email. (By default, Email will be automatically detected and mapped, but if the mapping is lost due to settings changes or other issues, please correct it as prompted.)

1. After completing the settings, click "Save"
2. Note: Push settings only take effect after you "Publish" or "Update Publish."

   While active, when the form receives new submissions, data will be pushed to Shopify in real time.

Reference: Data currently supported by Shopify

| Field            | Purpose                                              | Notes                                                                    |
| ---------------- | ---------------------------------------------------- | ------------------------------------------------------------------------ |
| Email (Required) | Customer email address, used to associate other data | Used as the unique identifier; ensure mapping is configured during setup |
| First name       | Customer first name                                  |                                                                          |
| Last name        | Customer last name                                   |                                                                          |
| Tag              | Tags can be used to group customers                  |                                                                          |
| Subscription     | Whether subscribed                                   | Defaults to subscribed; cannot be customized at this time                |

Note: Based on common Shopify use cases, emails collected and forwarded by Ptengine will automatically be marked as "Customer agreed to receive marketing emails." Please use accordingly, and if needed, inform users within the Experience content. We will optimize this setting in the future to support customization and accommodate more email collection scenarios.

## FAQ

### How Can I Sync Data to Shopify That Was Collected Before Push Setup or During Downtime?

Currently, the push mechanism works in real time when someone submits a form and data is collected. It only operates while the connection is active. For data collected before activation or during downtime, even if the form data is recorded in Ptengine's reports, it cannot be automatically pushed to Shopify after the connection is set up or restored.

In this case, you can manually download the form data from Ptengine and import it into the Shopify customer list.

Solution:

1. In the Experience report, switch to "Form Submissions" and click "CSV Download"
2. Go to Shopify, enter the "Customers" module, and click "Import" in the top right corner

Note: Please download the sample CSV and format the data accordingly before uploading.

### Can Ptengine Hide the Experience for Customers Who Have Already Subscribed?

Ptengine does not limit email usage to "subscription" scenarios, so it will not automatically stop displaying based on subscription status.

**For emails collected by Ptengine, you can hide the Experience by setting "Target Users":**

1. Click Experience Edit
2. Go to the "Target Users" module and click "Edit"
3. Switch to "Users meeting specific conditions," search for "email," and select the setting

Set the email condition to "is empty." This means the Experience will only be shown to users for whom no email has been collected.

This setting can be combined with other user targeting conditions, allowing you to create more diverse personalized configurations.

**For emails that already exist in the Shopify customer list, you can use the above method to specify "email exclusion."**

Note: To use this feature, you need:

[User Identification](https://help.ptengine.com/docs/ptx-user-identification/) configured in Ptengine

Visitors must be logged in (otherwise, the relationship between the browsing environment and the user's email cannot be established)

1. When excluding fewer than 1,000 emails

a. Open the email condition settings and select "Does not contain"

b. Paste the emails to be excluded (batch paste is supported) and save

2. When excluding more than 1,000 emails

This requires integration through other technical methods and support from your technical team. Please contact us if needed.

Ptengine can only control whether an Experience is displayed. Due to the nature of data push, it cannot verify whether a submitted email already exists in the customer list after submission. Therefore, if you distribute coupons after successful submission and need to limit coupon usage, please configure this through the Shopify admin in the checkout step.