Shopify Connector Setup

Owned by Morten Lindequist Køhler
Last updated: May 02, 2024 by lkj
51 min read

Shopify Connector setup parameters are defined in Connector’s configuration file and also in Perfion ECommerce mappings. Shopify Connector use Perfion ECommerce API and Shopify Admin API to synchronize data between Perfion and Shopify. Shopify Connector acts as master of data. All data synchronization is done from Shopify Connector, e.g. there is no active Shopify involvement in the synchronization process. Perfion Shopify Connector reads all required data from Shopify, compares it to what it is stored in Perfion and performs synchronization accordingly.

Shopify Connector in essence is a code library which implements Shopify synchronization manager. The library can be integrated into a custom project, but Perfion also offers a few end user friendly applications, which use the before mentioned library to perform synchronization. Currently there are following options:

  • C# dynamically linked library. The library allows to start and stop Shopify synchronization manager and also to subscribe to some events, which provide information what the manager is doing. This library is used by all other Connector applications offered by Perfion and it can also be used when building a custom application or when integrating Connector to other projects.

  • Windows service. Windows service is a special application, which can be installed in Windows OS and then it runs in a background. It will be controlled by Windows OS, e.g. it can be started automatically when Windows starts.

  • Console application. A console application is Windows OS executable file, which can be run from a command line.

Prerequisites

Before using the Shopify Connector the following Perfion components have to be installed:

  • Perfion application (optional). Perfion is a cloud based solution, so all the data Shopify Connector is using is in remotely accessible database. Connector communicates with this database by using Perfion ECommerce API, so for Connector itself to run, the Perfion application is not needed. The Perfion application is needed only to setup data, Connector related mappings and settings.

  • Perfion API Service. It consist of Perfion API, Perfion ECommerce API and other components.

Both prerequisites can be downloaded from Perfion Knowledge Base.

Shopify Connector versions and requirements. Shopify is continuously updated and with time Shopify Connector versions expire, because Shopify introduce breaking changes to their API. Because of this, always update to the newest version of Shopify Connector. The table below shows what is the newest version of Perfion Shopify Connector at the time of writing and which minimum versions it supports.

Shopify Connector version

Shopify API version

Expiration date

Perfion API version

Compatible Perfion version

1.6

2019-10

2020-10-01

4.5.52 or newer

2019 R1 (4.5.52) or newer

1.7

2020-01

2021-01-01

4.5.52 or newer

2019 R1 (4.5.52) or newer

1.9

2020-04

2021-04-01

4.5.52 or newer

2019 R1 (4.5.52) or newer

1.10

2021-01

2022-01-01

4.5.52 or newer

2019 R1 (4.5.52) or newer

1.11

2021-10

2022-10-01

4.5.52 or newer

2019 R1 (4.5.52) or newer

1.12

2022-01

2023-01-01

4.5.52 or newer

2019 R1 (4.5.52) or newer

1.13

2022-10

2023-10-01

4.5.52 or newer

2019 R1 (4.5.52) or newer

1.14

2023-10

2024-10-01

4.5.52 or newer

2019 R1 (4.5.52) or newer

Shopify releases a new stable API version every 3 months and there can be up to 4 stable API versions at any time. It does not mean that Shopify Connector supports all of them, because different API versions may have breaking changes. The Shopify Connector is updated continuously to support at least 1 stable API version and that version is provided in the table above. This version is the minimum version Shopify Connector allows. This means that one cannot choose earlier version than the version provided in the table. However, one may be able to choose a newer version, but it depends on changes introduced in new Shopify API versions. We recommend to use the minimum supported Shopify API version with Shopify Connector.

One can read more about Shopify API versioning here: https://help.shopify.com/en/api/versioning .

Shopify Connector Configuration File

Shopify Connector uses configuration file which is used to initialize Shopify Connector synchronization manager when Connector is used as Windows service or as console application. The configuration file is located in Shopify Connector installation folder. There are several configuration files available in installation folder and each file is dedicated to different Shopify Connector applications. All configuration file parameters are shown in the table below:

Parameter name

Description

ServiceName

Name of Shopify Connector application, which will be used when logging.

Recommendation: use short name without spaces.

PerfionChannelName

Perfion channel name. Connector will synchronize data only for one channel.

LogDirectory

Directory where log files will be saved. The log file will be dynamically created from date and ServiceName parameter value. The format of log file name will be: <date>_<ServiceName>_log.txt. There will be created one log file per day.

Date format: YYYYMMDD.

LogType

Type of log messages written to log file. The following values can be defined:

  • “Error” – logs only error messages.

  • “Warning” – logs Error and Warning messages.

  • “Progress” – logs Error, Warning and Progress messages. Progress type log messages show what is happening without going into details.

  • “Info” – logs Error, Warning, Progress and Info messages. Info type log messages are very detailed and may be useful for debugging

  • “Debug” – logs all messages. Debug level adds raw requests and responses from both APIs (Shopify and ECommerce). Note: API requests and responses includes all data sent via Shopify Connector, so it writes a lot of information to the log file. If ECommerce setup uses embedded images, then this data will be also written to the log file as it comes from API. It is recommended to use this log level only with limited amount of synchronization data. For example, if there is some product, which is not synchronized correctly, one can find exactly what is happening by enabling debug logging, but then it is best to turn all other synchronization data off to limit data amount written to the log file.

Default: “Progress”

ProgressReportStepInPct

The step in percent (%) refers to how often Shopify Connector will write synchronization status update for entity (product or category).

Default: 10

Values: 1-99

Note 1: Reporting of status depend on how many entity items are synchronized. If there are only 3 items, then the first reported status will be after the first item is synchronized and will be 33.3%, the next one will be 66.6%, etc.

Note 2: The status reporting is based on overall entity synchronization progress, which means that progress reporting will not be independent per entity item creations, updates and deletes.

ECBaseURL

Base URL to Perfion API, e.g. where ECommerce API and Perfion API queries can be called from.

ECBearerToken

Bearer Token to Perfion API. Optional if the Perfion API has SecureApiService=false. (Introduced in Shopify Connector 1.14)

ECRetryCount

Number of retries for failed ECommerce API requests.

Default: 3

Values (integer): >= 0

ECTimeoutInSec

Request to ECommerce API timeout in seconds.

Default: 300 seconds

Values (integer): >= 0 (0 - unlimited)

NOTE: The default timeout for web service configuration in Microsoft IIS server is 120 seconds for connection timeout and 110 seconds of execution timeout. If the value specified by this parameter exceeds timeout values set in IIS server, then it will not be effective until IIS server timeout values are also updated to the same or higher values.

  • Execution timeout value can be changed by adding an extra parameter to site’s web.config file, which is defined to be used for Perfion API and ECommerce API. For example:<system.web><httpRuntime executionTimeout="300" /></system.web>

  • Connection timeout can be changed in IIS Manager for site defined to be used for Perfion API and ECommerce API. One can change connection timeout value from “Advanced Settings…” in “Connection Limits” properties.

ECDataChunkSize

Number of entity items ECommerce API will retrieve at a time. Shopify Connector processes data in chunks to limit needed resources to process data. This parameter defines how many items will be handled at once.

Default: 25 items

Values (integer): > 0

NOTE: ECommerce API and Shopify API supports embedded (Base64 encoded) images and if these are used, then there is a risk that data chunk retrieved from ECommerce API may fail because of too large response document size. This parameter allows to adjust the size of response document.

NOTE: The data from ECommerce API is requested asynchronously, e.g. data from Perfion is retrieved at the same time when data is synchronized with Shopify, and the size of chunk has almost no effect on performance.

ShopifyRetryCount

Number of retries for failed requests to Shopify.

Default: 3

Values (integer): >= 0

ShopifyTimeoutInSec

Request to Shopify server timeout in seconds.

Default: 60 seconds

Values (integer): >= 0 (0 - unlimited)

EnableStatistics

Enables or disabled statistics calculation.

Default: false

Values (boolean): True|False

The Connector will synchronize data only for one Perfion channel. If multiple channels has to be synchronized, then one has to use multiple Shopify Connectors and configure them independently. Moreover, two independent Connectors cannot be used with the same Perfion channel data and the same Shopify store.

Connector configuration file will be used only by Windows service and console application. In custom applications built using Connector manager library, one can choose how to initialize all parameters.

Shopify Connector as Windows Service

Windows service must be installed before use.

Windows Service Installation

To install Shopify Connector as Windows service:

  1. Download the Shopify Connector files from Perfion support site.

  2. Place all files into folder, e.g. “C:/PerfionShopifyServiceA”. If several Shopify stores should be synchronized from Perfion, for example, with different languages, then the same procedure should be done for each store.

  3. Find Windows service install utility files. They must be located in the following folder: "C:\Windows\Microsoft.NET\Framework64\"

  4. There should be several .NET versions available, where each are located in separate folders. Use one, which is above v4. For example: "C:\Windows\Microsoft.NET\Framework64\v4.0.30319\".

  5. From the folder found in step 3. select files listed below and copy them to the installation folder created in step 2.

    1. InstallUtil.exe

    2. InstallUtil.exe.config

    3. InstallUtilLib.dll

  6. Open “Windows Command Prompt” or “PowerShell” with administrator user privileges and navigate to Shopify Connector installation folder created in step 2.

  7. Install the Shopify Connector by running this command:

Shopify Connector installation

InstallUtil.exe /servicename="<unique_service_name>" ShopifyService.exe

“<unique_service_name>” is the new unique name of Shopify Connector, which will be used by Windows, e.g. in Windows Services application. If several Shopify stores has to be synchronized, then for each store a new Shopify Connector service has to be installed with a new and unique name. Each Shopify Connector service will read data from a single Perfion channel, so we recommend naming each based on which Perfion channel will be used for data synchronization.

After installation of Shopify Connector service it will be available from Windows Service application. To open it press “Win+R” and then in “Run” window “Open:” field write “services.msc” and press “Enter”. Example of Windows Services application after installation is shown in Figure 1.

Figure 1: Windows Services application

  1. Update Shopify Connector configuration file. Before starting the Shopify Connector service it is important to update its configuration file with correct parameters. There are several configuration files in installation folder. Use “ShopifyService.exe.config” file to update Connector parameters. Refer to “Shopify Connector Configuration File” to see which parameters can be used in configuration file and how to correctly set them up.

  2. Note: Shopify Connector service must be restarted after each modification of configuration file.

  3. Start the service. Select the service in Windows Services application and start it by clicking green “Play” button in application toolbar or by right clicking on service name with a mouse and from context menu choosing “Start”. The service can be stopped by selecting it and then pressing “Stop” button in application toolbar or by right clicking on service name with a mouse and from context menu choosing “Stop”.

Windows Service Update

To update the Shopify Connector service it does not have to be reinstalled. The procedure:

  1. Stop the service.

  2. Overwrite the old service executable (ShopifyService.exe) and any library files (*.dll) with new service files.

  3. Note: do not overwrite configuration file (ShopifyService.exe.config), keep the old one.

  4. Compare old configuration file to the new configuration file coming with installation. If there are new parameters in the new configuration file, then they have to be added to the old configuration file. The default configuration file parameters coming with Shopify Connector installation use recommended values, but they are all user configurable.

  5. Start the service again.

Windows Service Removal

The removal procedure of Shopify Connector service:

  1. Open “Windows Command Prompt” or “PowerShell” with administrator user privileges and navigate to Shopify Connector service installation folder.

  2. Run the following command:

Shopify Connector removal

InstallUtil.exe /u /servicename="<unique_service_name>" ShopifyService.exe

“<unique_service_name>” is the same name as it was used when installing the service.

Shopify Connector as Console Application

Shopify Connector as console application is an independent executable file and does not need to be installed. There are several ways to start the Connector as a console application:

  • By executing the Connector console application executable file “ShopifyConsoleApp.exe” directly from Windows file browser. The executable file is in Connector installation folder.

  • By running the Connector console application from a command line interface in a manager mode. To do that first open “Windows Command Prompt” or “PowerShell” and then start the application by running the following command:

Running Connector as console application from command prompt

ShopifyConsoleApp.exe

  • By running the Connector console application from a command line interface in a single synchronization mode. This mode differs from the default mode, because in this case the Connector will not start in a manager mode, but instead will perform a single synchronization and then will quit. To run Connector in a single synchronization mode, run the following command:

Running Connector in a single synchronization mode from command prompt

ShopifyConsoleApp.exe -runonce

Before starting the Shopify Connector console application it is important to update its configuration file with correct parameters. There are several configuration files in installation folder. Use “ShopifyConsoleApp.exe.config” file to update Connector parameters for console application. Refer to “Shopify Connector Configuration File” to see which parameters can be used in configuration file and how to correctly set them up.

To stop the Connector, just close the application window. The Connector is designed to be abruptly stopped at any time. There could be some issues with some entity items which were under synchronization during Connector termination, but Connector was design to resynchronize all failed items on next start.

Shopify Connector as Library for a Custom Application

The Shopify Connector can be integrated into other projects or one can create a custom Connector application, which has a custom logger or even GUI. To do that one has to use Perfion Shopify Connector manager library. Refer to “Appendix A: Code Example of Connector as a Custom Console Application” to see an example of code which shows how to create a custom console application which uses most of Connector’s features.

The Connector manager have the following features:

  • The manager can be initialized with a custom logger. The standard Shopify Connectors in a form of console application and Windows service use a logger, which writes log messages to a text file. The user is, however, not limited to that and can use their own logger to get all information from manager and to control how and where the log messages will be saved. The example of a custom logger is provided in “Appendix A: Code Example of Connector as a Custom Console Application”.

  • The Connector manager consist of three interfaces and each interface may have its own independent logging.

    • Perfion Ecommerce API. Handles any communication with Perfion.

    • Shopify Admin API. Handles any communication with Shopify.

    • Connector manager. The manager, which uses Perfion Ecommerce and Shopify Admin APIs to perform a synchronization of data and also manage synchronization scheduling tasks.

  • Manager can be started. One can start the manager only if it is in initialized state or in stopped state. When starting the manager one can choose to start it in default manager mode where scheduled synchronization will be initialized or to choose to synchronize data once.

  • Manager can be stopped. One can stop the manager only if it is started. The stopping procedure will check which state the manager has and will handle stopping procedure accordingly. If the manager is sleeping or downloading new configuration, then it will be stopped immediately. In case the manager is performing synchronization, then it will try to stop it nicely. All synchronization items which were started to be synchronized will be allowed to finish and only then the manager will be stopped. For example, if there are 100 items to synchronize and manager have completed synchronizing 20 items, 5 items are currently being synchronized and 75 items are still waiting to be synchronized. The manager stopping procedure will allow to finish synchronization of those 5 items and will ignore the remaining 75 items.

  • Manager has four events, where each is triggered when manager state is changing.

    • State change event. The event is fired when manager changes its main state. For example, from “UpdatingConfiguration” to “Synchronizing”, from “Synchronizing” to “Sleeping”, etc.

    • Error state change event. The event is fired when:

      • Manager fails for any reason in any of its states, e.g. if it fails to retrieve the configuration or synchronization fails.

      • Manager is stopped externally. This will happen if the manager is stopped using “Stop” method.

      • Manager error state is restored when it retries after failure. The manager is running in continuous loop and activates predefined actions at predefined time intervals. If some error is detected, e.g. while retrieving configuration, then it will try again later. Any time when it retries, it restores the error state.

    • Synchronization type change event. This event is fired only when manager starts synchronization process. The synchronizer has its own states and triggers event when these states changes. For example, from “SyncStarted” to “CategorySync”, from “CategorySync” to “ProductSync”, etc.

    • Synchronization progress change event. This event is fired only when synchronizer is synchronizing categories or products and it reports the following information every time a single item have finished synchronizing (e.g. synchronization of a single product was completed):

      • The total progress of synchronization (for categories or for products) in percent.

      • The status of the last updated item if it has failed or succeeded.

    • Each triggered event will also provide a copy of the current Connector manager state after that moment the event was triggered, e.g. with a new state. Each event will also provide the state/progress it had before the change and after the change.

  • The manager can report all information related to its current state. The managers current state has the following information:

    • Manager state.

    • Manager error state.

    • Manager synchronization state. Note, usable only when manager is in synchronization state.

    • Synchronization information.

      • Synchronization type.

      • Entity synchronization total progress in percent (including creations, updates and deletions).

      • The number of items found for creation.

      • The number of items found for update.

      • The number of items found for deletion.

      • The total number of succeeded items so far.

      • The total number of failed items so far.

      • Note, it has useful information only when the manager is in product or category synchronization state. Most of provided information is related to the entity, which is being synchronized at the moment, which can be either category or product.

    • Sleep information.

      • Time left until Connector wakes up.

      • Date when Connector is expected to wake up from sleeping.

      • Note, usable only when manager is in sleeping state.

ECommerce Data Mapper in Perfion

ECommerce data mapper is a special data structure in Perfion, which is used to map data from Perfion to ECommerce API. There are four requirements when setting up data in ECommerce mapper:

  1. The ECommerce data structure must be installed in Perfion. This can be done from Perfion application. Refer to “ECommerce API” manual for more info.

  2. The data in Perfion must be setup correctly so that one can use it via ECommerce API. For example product variants should be linked to products in a special way, product variant dimensions must be specified correctly, etc. Refer to “ECommerce API” manual for more info.

  3. The ECommerce mapping settings should be set up correctly to be able to access product, variant, category, etc. data. Moreover, one must set up channels, image service location, file service location, image processing parameters, etc. Refer to “ECommerce API” manual for more info.

  4. ECommerce mapping settings should be configured to support Shopify Connector. The ECommerce API is a universal API created to extract data from Perfion, which is suitable for most E-Commerce systems. The first three requirements in this list covers general setup required to link Perfion data to ECommerce API. The Shopify E-Commerce system requirements are more specific and Shopify Connector will be able to read data from ECommerce API correctly only if all data is defined exactly as required. It means that all parameters must have special names, types, all mandatory parameters must be specified, etc.

The following sections will show how to set Shopify Connector specific parameters. These parameters are configured in sub-features, defined under “ECommerce Features”. Shopify Connector specific parameters will be defined in “ECommerce Mapping” and “ECommerce Settings” features. Refer to Figure 2.

Figure 2: ECommerce Features

ECommerce Data Mapper – Settings

Settings are defined in “ECommerce Features” -> ”ECommerce Settings”. Settings are global parameters and will be valid for all data synchronized from Perfion to Shopify. The purpose of settings can be compared to Shopify Connector configuration file. The main difference is that any settings parameters defined in Perfion will be continuously updated in Shopify Connector without a need to restart the Connector’s manager. How often these settings will be updated in Shopify Connector users can define in these settings. When Connector is started for the first time, it will read these settings parameters and will determine when data has to be updated again based on parameter values. Settings parameters related to Shopify Connector are shown in the table below. There can also be defined other settings parameters, which are generic for ECommerce API and information on those parameters can be found in “ECommerce API” manual.

ECommerce Settings Parameter

Description

ShopifyStoreBaseUrl

The base URL of Shopify store, e.g. “https://<store_name>.myshopify.com”

Parameter is mandatory

ShopifyApiVersion

Shopify API version. If not specified Perfion Connector will choose the minimum supported Shopify API version. In case the minimum supported Shopify API version is not supported anymore, then Shopify will automatically use the oldest stable API version to respond to Shopify Connector’s request.

Parameter is optional.

Format: YYYY-MM

ShopifyStoreAPIKey

Connection via Shopify admin API credentials – API key. It can be obtained from Shopify after creating Shopify Private app.

Parameter is optional.

Note that Shopify deprecated the Private apps which cannot be created anymore. Instead of Private apps Shopify introduced Custom apps. For more information refer to Shopify Private and Custom App Authentication.

ShopifyStoreAPIPassword

Connection via Shopify admin API credentials – API password. It can be obtained from Shopify after creating Shopify Private app.

Parameter is mandatory if Shopify admin API access token is not defined.

Note that Shopify deprecated the Private apps which cannot be created anymore. Instead of Private apps Shopify introduced Custom apps. For more information refer to Shopify Private and Custom App Authentication.

ShopifyStoreAPIAccessToken

Connection via Shopify admin API credentials – access token. It can be obtained from Shopify after creating Shopify Custom app.

This parameter is mandatory when using Shopify Custom app. If this parameter is defined then the API key and password fields will be ignored. For more information refer to Shopify Private and Custom App Authentication.

SyncType

Comma separated synchronization types.

Parameter is optional.

Default value: <no value> (no synchronization)

Values:

  • Add – allow to add new data to Shopify, e.g. data, which is not yet created in Shopify.

  • Update – allow to update existing data in Shopify, e.g. when data in Perfion is linked to data in Shopify.

  • Deactivate – allow to deactivate existing data in Shopify, which is no longer in Perfion or marked in Perfion as not for synchronization. Note: this value does not mean that it allows or not to deactivate selected products or other data in Shopify, but rather that Shopify Connector will use deactivation instead of deletion when necessary based on how data is set up in Perfion. Since products and custom collections can be manually activated and deactivated using “Publish” and “Published” parameters accordingly, these parameters will be overwritten by Shopify Connector during synchronization if products or custom collections has to be deleted from Shopify and “Deactivate” synchronization type is defined.

  • Delete – allow to delete existing data in Shopify. The same as “Deactivate”, but this parameter value will allow physical data deletion.

ConfigurationUpdateFrequencyInMin

Time in minutes how often Shopify Connector manager will check for channel configuration changes.

Parameter is optional.

Default value: 0 (no update)

Values (integer type): >= 0

SyncFrequencyInMin

Time in minutes how often synchronization should run.

Parameter is optional.

Default value: 0 (no synchronization)

Values (integer type): >= 0

DataMaxAgeInMin

Time in minutes how often data has to be refreshed/resynchronized. Based on this parameter value, data for synchronization will be chosen using an extra condition, which will check if data is not older than specified value since the data was last synchronized. For example, if parameter value is set to 1 month and product was not modified in the last month, then synchronization will update it anyway to make sure that all items in Shopify has data, which is not older than 1 month.

Parameter is optional.

Default value: 0 (no data refresh)

Values (integer type): >= 0

Languages

Comma separated values of Perfion language codes. For Shopify one can use only one value, because Shopify does not support multiple languages in a single store. If more than one value is specified, then only the first one will be used in Shopify Connector.

Parameter is mandatory

SyncCategories

Enables category synchronization.

Parameter is optional.

Default value: false (existing custom collections in Shopify will not be touched, e.g. if there were any).

Values: true|false

UpdateUnpublishedItems

Enables synchronization of unpublished (deactivated) product and category items.

Parameter is optional.

Default value: false (unpublished items are not synchronized).

Values: true|false

KeepExistingVariantData

The parameter controls how product variants are updated during synchronization. Shopify Connector recreates variants on each product update. When creating new variants, Shopify Connector will only use the data coming from Perfion to save variants, e.g. any other data existing in Shopify will be discarded. This is default behavior of Shopify Connector. In order to change this behavior and to keep some of existing variant data, one has to set this parameter value to ‘true’.

Parameter is optional.

Default value: false (all variants will be overwritten with data from Perfion)

Values: true|false

SuppressMissingMetafieldWarnings

The parameter controls logging of warnings related to product, variant and category metafields. Metafields are custom Shopify parameters, which can be defined for all mentioned entities and their configuration is fixed even though different entity items may need to use different metafields.

For example, products of type “shoes” may need additional metafield to be used with its variants, which will define the size of the shoes, while products of type “clothes” may need extra metafield, which will define washing instructions. To support both cases, there should be defined two metafields or one, which will be shared by both types of product variants.

The configuration is fixed and Shopify Connector issues warnings if data is configured to be used, but data is not defined for entity item. So if independent metafields will be used for different entity items, then Shopify Connector will issue warnings for those entity items, which do not have metafields, which are only used with other entity items.

For example, if variants for shoes will not have metafield data with washing instructions, then a warning will be issued for that item. This is not an error and data will synchronize correctly (not defined metafield will be assumed as not existing and removed from Shopify), but it may send too many warnings which will make detection of more important issues complicated.

The warnings are necessary in order to warn user about missing mandatory data. Shopify metafields cannot have empty value, so if the data is not defined in Perfion by user for all items, then there is no default value, which can be sent to Shopify.

Parameter is optional.

Default value: false (missing metafield warnings will not be suppressed)

Values: true|false

RefLoc_1

Shopify locations mapping. Shopify store may have many locations which are used with Shopify’s inventory system. The inventory system tracks product variants based on locations and in order to fully utilize variant data synchronization, all locations referenced in product variant quantity updates must be predefined here in ECommerce Settings.  One can use normal locations and also fulfillment locations.

Reference locations are defined using custom format:

“RefLoc_<label>”, where “label” is a unique label to identify the location. All location references must be unique per channel.

Parameter is optional, but there must be at least one location definition if one wants to synchronize variant quantities.

Default value: none

Values: the exact name of location from Shopify (Options->Locations).

RefLoc_2

…

RefLoc_N

Note that if none of “ConfigurationUpdateFrequencyInMin”, “SyncFrequencyInMin” and “DataMaxAgeInMin” parameters are specified, then Shopify Connector will use its own default value of 10 minutes to update channel configuration.

Shopify Private and Custom App Authentication

Shopify deprecated the Private apps and they cannot be created anymore, but the old Private apps can still be used.

Instead of Private apps Shopify introduced Custom apps, which are basically the same as Private apps, but they changed how the authentication works and instead of using API key and password one has to use the access token.

There are several different ways how to authenticate the Private and Custom apps when using Shopify Connector.

  • Using access token – This method works with Custom and Private apps. The method will be used if access token is defined. API key and password fields will be ignored when access token is defined, however, Private app can be authenticated using API password as access token.

  • Using API password – This method works with Private apps and is an alternative way to authenticate to the original method where API key and password were used. To use this method the access token and API key fields must be left blank. In this case the Connector will use the access token authentication by using API password as access token. To use this method the API key must be left blank.

  • Using API key and password – This method works with Private apps and is the original/old way to authenticate the Private app. To use this method the access token must be blank and API key and password should be defined.

ECommerce Data Mapper – Mapping

Mappings are defined in “ECommerce Features” -> ”ECommerce Mapping”. Mappings are related to actual product, variant, category, etc. data. Like settings parameters, mapping parameters will be continuously updated in Shopify Connector manager without a need to restart it. Mapping parameters related to Shopify Connector are shown in the tables below, based on data type. There can also be defined other mapping parameters, which are generic for ECommerce API and information on those parameters can be found in “ECommerce API” manual.

Product Mapping Parameters

For all product related mapping parameters “ECommerce Entity” column value must be set to “Product”.

To

Output Kind

Mapping

Description

Key

KeyField

Name of Perfion feature (String type).

Values are of string type and must be unique for all product items.

Key will be used to link Perfion items to the same items in Shopify.

Mandatory parameter.

This is a Sync parameter.

SyncID

Field

Name of Perfion feature (String type, not Inheritable).

Values are of string type.

SyncID will be used to link product ID defined by Key parameter to external ID of the same item in Shopify.

Mandatory parameter.

This is a Sync parameter.

SyncDate

Field

 

Name of Perfion feature (String type, not Inheritable).

Values are of string type.

Date format: “yyyy-MM-dd HH:mm:ss” e.g. “2018-02-12 17:15:09”.

SyncDate is used to show the last synchronization date and it is also used to find out when data has to be synchronized next time. This parameter will be updated from Shopify Connector after the item is synchronized. If there was any error while synchronizing the item, then date will not be updated.

Mandatory parameter.

This is a Sync parameter.

SyncType

Field

 

Name of Perfion feature (String type, not Inheritable).

Values are of string type.

Allowed values:

  • “” (empty string)

  • “NoUpdate”

  • “UpdateOnce”

Default value: “”.

Value defined for this parameter will allow to overwrite default synchronization settings for each product.

Parameter is optional.

This is a Sync parameter.

Refer to “Product SyncType Parameter” for more information.

SyncMsg

Field

Name of Perfion feature (Text type, not Inheritable).

Values are of string type.

SyncMsg will be used for synchronization error reporting for each product.

Mandatory field.

This is a Sync parameter.

SyncProduct

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Product synchronization status.

Parameter is optional.

This is a Sync parameter.

If defined with “true”, the product will be synchronized with Shopify. If “false”, then the product will be treated as if it does not exist in Perfion. E.g. if Shopify has this product and value is set to “false”, then product will be removed from Shopify.

SyncDefaultVariant

Field

String values true|false, or Perfion feature (String type)

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Product default variant synchronization status.

Parameter is optional.

This is a Sync parameter.

If set to “true”, the Connector will create a default variant from the product item and will sync with Shopify. The default variant is a simplified version of normal variant. When default variant synchronization is enabled, the Connector will use the data specified by DefaultVariant* product mappings.

If set to “false” and the SyncVariants is not enabled, then the standard variant will be added to the product, which is a special way in Shopify to define that product does not have variants.

SyncVariants

Field

String values true|false, or Perfion feature (String type)

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Product variant synchronization status.

Parameter is optional.

This is a Sync parameter.

If set to “true”, the Connector will synchronize variants. This will automatically add options and variants to the product.

If set to “false” and the SyncDefaultVariant is not enabled, then the standard variant will be added to the product, which is a special way in Shopify to define that product does not have variants.

SyncCollections

Field

String values true|false, or Perfion feature (String type)

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Product relation to categories synchronization status.

Parameter is optional.

This is a Sync parameter.

If set to “true”, will add product relations to categories (custom collections). For this to work, the category synchronization should be set up correctly, e.g. SyncCategories settings parameter must be set to “true”, category mappings should have SyncCollection set to “true” and other category mappings must to be set correctly.

SyncImages

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Product image synchronization status.

Parameter is optional.

This is a Sync parameter.

If set to “true“, will use product images.

If set to “false”, will remove all images from product.

SyncMetafields

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Product metafield synchronization status.

Parameter is optional.

This is a Sync parameter.

SyncKeepDeletedMetafields

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Product metafield synchronization parameter. If set to “true” it will not delete any existing metafields in Shopify and will only add new metafields and will update existing ones.

This parameter will also be used when determining if product variant metafields has to be deleted.

Parameter is optional.

This is a Sync parameter.

Collections

RelatedCategory

Perfion feature for product category. The value should be set with the same feature name, which is used as base feature in Category Context definition. For example, if Category Context is defined as ”Website/WebDetail/ECommerceCategorySearch”, then “Website” will be the name of the base feature and should be used as value with this parameter.

This is a special parameter, which allows to specify the link from Perfion product to Perfion category, which will be converted to the link from Shopify product to Shopify custom collection by using Shopify collects.

Parameter is optional.

This parameter is used only when SyncCollections is set to “true”.

Refer to “ECommerce API” manual for more information how it has to be set up.

 

Options

VariantDimension

String value or name of Perfion feature (String type).

Values are of string type.

The value is a comma separated list of feature names (unique feature name should be used), which define product variant options.

Default value: “” (empty string).

Product variant options.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is a standard option which has name set to “Title” and one value: “Default Title”.

The parameter is used only when SyncVariants and/or SyncDefaultVariant parameter is set to “true”.

Refer to “ECommerce API” manual for more information how it has to be set up.

Images

Image, Field, Attachment

String value (for Field output kind only) or name of Perfion feature.

Supported feature base types for different output kinds:

  • Image: Image type feature

  • Field: String value, or feature of String or Text type

  • Attachment: File type feature

Default value: <none> (images will be removed from Shopify)

Product and product variant images.

Parameter is optional.

This is a Shopify parameter.

The parameter will be used only if SyncImages is set to “true”.

Metafield|<namespace>|<key>|<type>

Field

Name of Perfion feature (String type).

Values are of string type.

Default value: “” (the metafield will be removed from Shopify if not defined).

Product metafield parameter. One can define multiple metafields, but “namespace” and “key” combined value must be unique.

“namespace” must have min 2 chars, max 20 chars and allowed characters are: A-Za-z0-9_.~-@#*$.

“key” must have min 3 chars, max 30 chars and allowed characters are A-Za-z0-9_.~-@#*$

“type” parameter may have many values. Refer to Metafield Handling in order to see all supported values.

Parameter is optional. If not defined the ‘string’ type will be used by default.

This is a Shopify parameter.

The parameter will be used only if SyncMetafields is set to “true”.

Metafield|<namespace>|<key>|<type>@description

Attribute

Name of Perfion feature (String type).

Values are of string type.

Product metafield value description. It is optional and can only be used if metafield value is defined.

When defining metafield value description the To mapping should have the same string as the metafield value has, but then at the end one has to add a suffix “@description”. An example how to set up metafield value and value description can be found here: Metafield Handling.

Metafield|global| title_tag|string

Field

The same rules as for standard metafield (Metafield|<namespace>|<key>|<type>)

 

Special case of product metafield. This metafield is used by Shopify and has a fixed format. It is used as the name of the product used for SEO purposes. Generally added to the <meta name='title'> tag.

This metafield is defined in Shopify with string type value, namespace set to “global” and key set to “title_tag”.

Metafield|global| description_tag|string

Field

The same rules as for standard metafield (Metafield|<namespace>|<key>|<type>)

 

Special case of product metafield. This metafield is used by Shopify and has a fixed format. A description of the product used for SEO purposes. Generally added to the <meta name='description'> tag.

This metafield is defined in Shopify with string type value, namespace set to “global” and key set to “description_tag”.

Title

Field

String value or Perfion feature (String type).

Values are of string type and cannot be empty.

Name of the product.

Parameter is mandatory.

This is a Shopify parameter.

BodyHtml

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: “” (empty string).

Description of the product. Supports HTML formatting.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “null”, e.g. not set.

Vendor

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: “” (empty string).

Name of the vendor of the product.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is the name of the Shopify store set in Shopify store settings.

ProductType

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: “” (empty string).

Categorization that a product can be tagged with, commonly used for filtering and searching.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “” (empty string).

Publish

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Product publishing status in Shopify, e.g. published or not.

Parameter is optional.

Default Shopify value is “true”.

TemplateSuffix

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: “” (empty string).

Suffix of the Liquid template being used. By default, the original template is called “product.liquid” without any suffix. Any additional templates will be: “product.suffix.liquid”

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “null”, e.g. not set.

PublishedScope

Field

String value or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “global”

  • “web”

Default value: “global”.

Indicates whether the product is published to the Point of Sale channel.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “global”.

 

Tags

Field

Comma separated string values or Perfion feature (String or Text type), which can be of multi-value type.

Values are of string type Maximum single tag length: 255 characters.

Categorization that a product can be tagged with. Commonly used for filtering and searching.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “” (empty string).

DefaultVariantPrice

Field

Decimal value or Perfion feature (String or Number type).

Values are of string type, but should have valid decimal value.

Default value: “” (empty string).

The price of default product variant.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “0.00”.

Value is sent to Shopify rounded to two decimal places.

The value if defined as string should use a dot as decimal separator.

DefaultVariantCost

Field

Decimal value or Perfion feature (String or Number type).

Values are of string type, but should have valid decimal value.

Default value: “” (empty string).

The unit cost of default variant (inventory item).

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “null”.

Value is sent to Shopify rounded to two decimal places.

The value if defined as string should use a dot as decimal separator.

DefaultVariantSKU

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: “” (empty string).

A unique identifier for the product default variant in the shop.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “” (empty string).

DefaultVariantBarcode

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: “” (empty string).

The barcode, UPC or ISBN number for the product default variant.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “null”, e.g. not set.

DefaultVariantQuantity

Field

Integer value or Perfion feature (String or Number type).

Values are of string type, but should have valid integer value.

Default value: 0 (empty string).

The quantity of the product variant for default Shopify store location.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “0”.

DefaultVariantWeight

Field

Integer value or Perfion feature (String or Number type).

Values are of string type, but should have valid integer value.

Default value: “0”.

The weight of the product variant for default Shopify store location.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “0”.

Introduced in version 1.15

DefaultVariantWeightUnit

Field

String value or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “g”

  • “kg”

  • “oz”

  • “lb”

Default value: “g”.

The unit of measurement that applies to the product variant's weight.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is Shopify shop's default unit of measurement.

Introduced in version 1.15

DefaultVariantOption1

Field

Perfion feature (String type).

Values are of string type.

Default variant option value for the 1st dimension.

Parameter is optional.

This is a Shopify parameter.

DefaultVariantOption2

Field

Perfion feature (String type).

Values are of string type.

Default variant option value for the 2nd dimension.

Parameter is optional.

This is a Shopify parameter.

DefaultVariantOption3

Field

Perfion feature (String type).

Values are of string type.

Default variant option value for the 3rd dimension.

Parameter is optional.

This is a Shopify parameter.

All product Shopify type parameters are directly related to Shopify. Refer to https://help.shopify.com/api/reference/product#properties for more information about these parameters.

Synchronization parameters are used to determine the scope of synchronization, which items has to be synchronized, relate Perfion items to Shopify items, etc. Read more about how synchronization parameters are used in “Overview of Synchronization Process Parameters”.

All Shopify parameters, which are optional can be removed from mappings and Shopify Connector will not send them to Shopify. This means that any existing data in Shopify defined by those not used parameters, will not be overwritten by Shopify Connector.

Product SyncType Parameter

Product SyncType parameter allows to overwrite the default synchronization parameters for individual products. 

SyncType Value

Description

<Empty>

If the value is not set (e.g. empty string), then global synchronization settings will be used to determine how this entity item will be synchronized. This is a default value.

NoUpdate

This value will indicate that product item should not be updated in Shopify. For example, this could be a temporary product, which is created in Perfion, but should not be updated yet. If the product already exist in Shopify, then it will be ignored, e.g. not updated and not deleted or deactivated. If the product does not exist in Shopify, then it will not be created in Shopify. Example:

Product variants has special prices, and has to be updated only when e.g. there is some event (black Friday, Christmas, etc.). All special products could be marked with “NoUpdate” SyncType value and then new prices can be added in Perfion without affecting data in Shopify. After the time for update comes, the products can be set back to original SyncType value to resume synchronization.

UpdateOnce

This value will indicate that product can be updated only once. The entity item will be updated during next synchronization and after synchronization the value of SyncType parameter will be set to “NoUpdate”. Since there is no direct control of Shopify Connector from Perfion, it may be difficult to know when data is updated. One cannot update the product data and then change the option to different value, because there can be a long delay between updates. This option allows to update product only once without keeping an eye when actual synchronization takes place.

Product Variant Mapping Parameters

For all variant related mapping parameters “ECommerce Entity” column value must be set to “Variant”.

Product variant is independent entity in Perfion like product, but in Shopify it is part of product data. Perfion synchronizes products and product variants comes together as part of product data. If anything in product data is modified and has to be updated, then all product data will be resynchronized. This means that variants do not have their own Shopify ID in Perfion and will be always replaced with new variants when product is update during synchronization. This also means that product variants in Shopify will not have a fixed ID one can refer to. Variant ID will be dynamic in Shopify. Instead one has to use variant parameter values such as “SKU” or “Barcode” to know if the product variant is the same variant or not. Alternatively one can also use product variant option values for variant identification. Option values are mandatory for product variants and there cannot be duplicate variants with the same combination of option values.

To

Output Kind

Mapping

Description

SyncVariant

Field

String values true|false, or Perfion feature (String type)

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Product variant synchronization status. If set to “false”, then variant will be treated as if it does not exist.

Parameter is optional.

This is a Sync parameter.

SyncMetafields

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Product variant metafield synchronization status.

Parameter is optional.

This is a Sync parameter.

 

SyncImage

Field

String values true|false, or Perfion feature (String type)

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Product variant image synchronization status.

Parameter is optional.

This is a Sync parameter.

If set to “true”, variant image will be used.

SyncAllImages

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Product variant all image synchronization status.

Parameter is optional.

This is a Sync parameter.

If set to “true“, will add all variant images to product images. Shopify allows to have only one variant image, so this option allows to add more images for each variant, but only the first found variant image will be linked to the variant. All other variant images will be added as additional product images.

Images

Image, Field, Attachment

String value (for Field output kind only) or name of Perfion feature.

Supported feature base types for different output kinds:

  • Image: Image type feature

  • Field: String value, or feature of String or Text type

  • Attachment: File type feature

Default value: <none> (images will be removed from Shopify)

Product variant images.

Parameter is optional.

This is a Shopify parameter.

The parameter will be used only if SyncImages is set to “true”.

Position

Field

Integer value or Perfion feature (String type).

Values are of string type, but should have valid integer value.

Default value: “” (empty string).

The order of the product variant in the list of product variants. “1” is the first position, but negative values are also allowed in Shopify.

If not defined, Shopify will use the default order as defined in Perfion or as it is read from database.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is assigned based on in which order variants are transferred to Shopify.

Price

Field

Decimal value or Perfion feature (String or Number type).

Values are of string type, but should have valid decimal value.

Default value: “” (empty string).

The price of the product variant.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “0.00”.

Value is sent to Shopify rounded to two decimal places.

The value if defined as string should use a dot as decimal separator.

CompareAtPrice

Field

Decimal value or Perfion feature (String or Number type).

Values are of string type, but should have valid decimal value.

Default value: “” (empty string).

The original price of the item before an adjustment or a sale.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “null” (not defined).

The value if defined as string should use a dot as decimal separator.

If the value is defined, then it should be higher than the value set in Price field.

Taxable

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Specifies whether or not a tax is charged when the product variant is sold.

This is a Shopify parameter.

Default Shopify value is “true”.

Sku

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: “” (empty string).

A unique identifier for the product variant in the shop.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “” (empty string).

Barcode

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: “” (empty string).

The barcode, UPC or ISBN number for the product variant.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “null”, e.g. not set.

Grams

Field

Decimal value or Perfion feature (String or Number type).

Values are of string type, but should have valid decimal value.

Default value: “0”.

The weight of the product variant in grams.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “0”.

The value if defined as string should use a dot as decimal separator.

WeightUnit

Field

String value or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “g”

  • “kg”

  • “oz”

  • “lb”

Default value: “g”.

The unit of measurement that applies to the product variant's weight.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is Shopify shop's default unit of measurement.

 

Weight

Field

Integer value or Perfion feature (String or Number type).

Values are of string type, but should have valid integer value.

Default value: “0”.

The weight of the product variant in the unit system specified by “WeightUnit” parameter.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “0”.

The value if defined as string should use a dot as decimal separator.

InventoryPolicy

Field

String value or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “deny”

  • “continue”

Default value: “deny”.

Specifies whether or not customers are allowed to place an order for a product variant when it's out of stock.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “deny”.

OldInventoryQuantity

Field

Integer value or Perfion feature (String type).

Values are of string type, but should have valid integer value.

Default value: “0”.

The original stock level the client believes the product variant has. This should be sent to avoid a Race condition  when the item being adjusted is simultaneously sold online.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “1”.

The parameter is Deprecated

InventoryQuantity

Field

Integer value or Perfion feature (String type).

Values are of string type, but should have valid integer value.

Default value: “0”.

The number of items in stock for this product variant.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “0”.

The parameter is Deprecated

InventoryQuantityAdjustment

Field

Integer value or Perfion feature (String type).

Values are of string type, but should have valid integer value.

Default value: “0”.

Instead of sending a new and old value for inventory, an adjustment value can be sent. If an adjustment value is sent it will take priority.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “null”, e.g. not set. This parameter is an intermediate parameter to set other parameters in Shopify, so it does not have any default value.

The parameter is Deprecated

FulfillmentService

Field

String value or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “manual”

  • Fulfillment service handle

Default value: “manual”.

Service which is doing the fulfillment. Possible values are “manual” or the handle of a https://help.shopify.com/api/reference/fulfillmentservice

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “manual”.

InventoryManagement

Field

String value or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “shopify”

  • Fulfillment service provider name

Default value: “shopify”.

Specifies whether Shopify tracks the number of items in stock for this product variant. Valid values are “shopify” or the name of a fulfillment service provider with inventory management enabled.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “null”, e.g. not set.

Cost

Field

Decimal value or Perfion feature (String or Number type).

Values are of string type, but should have valid decimal value.

Default value: “” (empty string).

The unit cost of variant (inventory item).

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “null”.

Value is sent to Shopify rounded to two decimal places.

The value if defined as string should use a dot as decimal separator.

Tracked

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “true”.

Specifies whether or not the variant (inventory item) inventory is tracked. If set to “true”, then inventory quantity changes are tracked by Shopify.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “true”.

DoNotUseDefaultQuantities

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

This parameter allows to change the default behavior how variant quantity is updated in Connector. By default, if quantities are defined in a mapping, but value for actual variant is not defined for location, then default 0 value is used. If variant mappings have more than 1 quantity specified and one of those quantities refer to location which is fulfillment location, then this parameter should be set to “true”. This is necessary, because when variant uses fulfillment service quantities there could be only 1 quantity specified while with default Connector behavior there will be more than 1.

Parameter is optional.

This is a custom Shopify Connector parameter.

RelocateIfNecessary

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “true”.

This parameter is used when updating variant (inventory item) quantity control scope from using fulfillment location to standard locations or vice versa.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “false”.

It is recommended to always set this parameter to “true”, or otherwise Product update may fail in some rare cases.

Refer to “https://help.shopify.com/en/api/reference/inventory/inventorylevel ” for more information.

DisconnectIfNecessary

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “true”.

This parameter is used when updating variant (inventory item) quantity control scope from using fulfillment location to standard locations or vice versa.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “false”.

It is recommended to always set this parameter to “true”, or otherwise Product update may fail in some rare cases.

Refer to “https://help.shopify.com/en/api/reference/inventory/inventorylevel ” for more information.

Quantity_<location1>

Field

Integer value or Perfion feature (String or Number type).

Values are of string type, but should have valid integer value.

Default value: 0 (empty string).

The quantity of the product variant for chosen location. The “To” mapping should match one of the location mappings specified in ECommerce Settings for the same channel. For example, “Quantity_RefLoc_1” will refer to location “RefLoc_1” defined in EC Settings. All quantity definitions must be unique (e.g. no duplicate quantity keyword is allowed for variant item for chosen channel).

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “0”.

Quantity_<location2>

…

Quantity_<locationN>

CountryCodeOfOrigin

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: null

The 2 char long code for the country where the variant (inventory item) was made.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “” (empty string).

HarmonizedSystemCode

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: null

The 6 char long general Harmonized System  (HS) code for the inventory item. Used if a country-specific HS code is not available.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “” (empty string).

ProvinceCodeOfOrigin

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: null

The 2 char long code for the province where the variant (inventory item) was made. Used only if the shipping provider for the inventory item is Canada Post.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “” (empty string).

RequiresShipping

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true” – shipping address is required

  • “false” – shipping address is not required

Default value: “false”.

Specifies whether or not a customer needs to provide a shipping address when placing an order for this product variant.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “true”.

Metafield|<namespace>|<key>|<type>

Field

Name of Perfion feature (String type).

Values are of string type.

Default value: “” (the metafield will be removed from Shopify if not defined).

Product variant metafield parameter. One can define multiple metafields, but “namespace” and “key” combined value must be unique.

“namespace” must have min 2 chars, max 20 chars and allowed characters are: A-Za-z0-9_.~-@#*$.

“key” must have min 3 chars, max 30 chars and allowed characters are A-Za-z0-9_.~-@#*$

“type” parameter may have many values. Refer to Metafield Handling in order to see all supported values.

Parameter is optional. If not defined the ‘string’ type will be used by default.

This is a Shopify parameter.

The parameter will be used only if SyncMetafields is set to “true”.

Metafield|<namespace>|<key>|<type>@description

Attribute

Name of Perfion feature (String type).

Values are of string type.

Product metafield value description. It is optional and can only be used if metafield value is defined.

When defining metafield value description the To mapping should have the same string as the metafield value has, but then at the end one has to add a suffix “@description”. An example how to set up metafield value and value description can be found here: Metafield Handling.

All product variant Shopify type parameters are directly related to Shopify. Refer to https://help.shopify.com/api/reference/product_variant#properties for more information about these parameters.

Synchronization parameters are used to determine the scope of synchronization, which items has to be synchronized, relate Perfion items to Shopify items, etc. Read more about how synchronization parameters are used in “Overview of Synchronization Process Parameters”.

All Shopify parameters, which are optional can be removed from mappings and Shopify Connector will not send them to Shopify. In this case, the Shopify will assign default values for all missing parameters.

The variant data is always recreated on product update. That means, that if there are any parameters in Shopify, which are not controlled by Perfion, then they will be removed during product update. In order to keep variant data existing in Shopify, but which is not controlled from Perfion, one has to set ECommerce Setting Mappings parameter KeepExistingVariantData to ‘true’. This allows keeping some of existing variant data, but enabling this option will affect product synchronization performance. Refer to “ECommerce Data Mapper – Settings” for more information about supported variant fields one can keep during update.

Category Mapping Parameters

For all category related mapping parameters “ECommerce Entity” column value must be set to “Category”.

If ECommerce Settings parameter SyncCategories is set to “false”, then any category mappings will be ignored. In this case, even if mappings are defined correctly, they will not be used and categories will not be synchronized or used anywhere in Shopify Connector.

To

Output Kind

Mapping

Description

Key

KeyField

Name of Perfion feature (String type).

Values are of string type and must be unique for all categories.

Key will be used to link Perfion category items to the custom collection items in Shopify.

Mandatory parameter.

This is a Sync parameter.

SyncID

Field

Name of Perfion feature (String type, not Inheritable).

Values are of string type.

SyncID will be used to link category ID defined by Key parameter to external ID of the custom collection in Shopify.

Mandatory parameter.

This is a Sync parameter.

SyncDate

Field

 

Name of Perfion feature (String type, not Inheritable).

Values are of string type.

Date format: “yyyy-MM-dd HH:mm:ss” e.g. “2018-02-12 17:15:09”.

SyncDate is used to show the last synchronization date and it is also use to find out when data has to be synchronized next time. This parameter will be updated from Shopify Connector after the item is synchronized. If there was any error while synchronizing the item, then date will not be updated.

Mandatory parameter.

This is a Sync parameter.

SyncMsg

Field

Name of Perfion feature (Text type, not Inheritable).

Values are of string type.

SyncMsg will be used for synchronization error reporting for each category.

Mandatory field.

This is a Sync parameter.

SyncCollection

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Category synchronization status.

Parameter is optional.

This is a Sync parameter.

If set to “true”, the category will be synchronized with Shopify.

If set to “false”, then the category will be treated as if it does not exist in Perfion. E.g. if Shopify has custom collection linked to category, then it will be removed from Shopify.

SyncMetafields

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Custom collection metafield synchronization status.

Parameter is optional.

This is a Sync parameter.

SyncKeepDeletedMetafields

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Custom collection metafield synchronization parameter. If set to “true” it will not delete any existing metafields in Shopify and will only add new metafields and will update existing ones.

Parameter is optional.

This is a Sync parameter.

Title

Field

String value or Perfion feature (String type).

Values are of string type.

Name of the custom collection.

Parameter is mandatory.

This is Shopify parameter.

BodyHtml

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: “” (empty string).

Description of the custom collection. Supports HTML formatting.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “null”, e.g. not set.

Published

Field

String values true|false, or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “true”

  • “false”

Default value: “false”.

Custom collection publishing status in Shopify, e.g. published or not.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “true”.

TemplateSuffix

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: “” (empty string).

Suffix of the Liquid template being used. By default, the original template is called “product.liquid” without any suffix. Any additional templates will be: “product.suffix.liquid”.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “null”, e.g. not set.

PublishedScope

Field

String value or Perfion feature (String type).

Values are of string type.

Default value: “global”.

The sales channels in which the custom collection is available.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “web”.

Image

Image, Field, Attachment

String value (for Field output kind only) or name of Perfion feature.

Supported feature base types for different output kinds:

  • Image: Image type feature

  • Field: String value, or feature of String or Text type

  • Attachment: File type feature

Default value: <none> (images will be removed from Shopify)

Custom collection image.

Parameter is optional.

This is a Shopify parameter.

SortOrder

Field

String value or Perfion feature (String type).

Values are of string type.

Allowed values:

  • “alpha-asc”: Alphabetically, in ascending order (A - Z).

  • “alpha-desc”: Alphabetically, in descending order (Z - A).

  • “best-selling”: By best-selling products.

  • “created”: By date created, in ascending order (oldest - newest).

  • “created-desc”: By date created, in descending order (newest - oldest).

  • “manual”: Order created by the shop owner.

  • “price-asc”: By price, in ascending order (lowest - highest).

  • “price-desc”: By price, in descending order (highest - lowest).

Default value: “created-desc”.

The order in which products in custom collection appear in Shopify.

Parameter is optional.

This is a Shopify parameter.

Default Shopify value is “best-selling”.

Metafield|<namespace>|<key>|<type>

Field

Name of Perfion feature (String type).

Values are of string type.

Default value: “” (the metafield will be removed from Shopify if not defined).

Custom collection metafield parameter. One can define multiple metafields, but “namespace” and “key” combined value must be unique.

“namespace” must have min 2 chars, max 20 chars and allowed characters are: A-Za-z0-9_.~-@#*$.

“key” must have min 3 chars, max 30 chars and allowed characters are A-Za-z0-9_.~-@#*$

“type” parameter may have many values. Refer to Metafield Handling in order to see all supported values.

Parameter is optional. If not defined the ‘string’ type will be used by default.

This is a Shopify parameter.

The parameter will be used only if SyncMetafields is set to “true”.

Metafield|<namespace>|<key>|<type>@description

Attribute

Name of Perfion feature (String type).

Values are of string type.

Product metafield value description. It is optional and can only be used if metafield value is defined.

When defining metafield value description the To mapping should have the same string as the metafield value has, but then at the end one has to add a suffix “@description”. An example how to set up metafield value and value description can be found here: Metafield Handling.

All category Shopify type parameters are directly related to Shopify. Refer to https://help.shopify.com/api/reference/customcollection#properties for more information about these parameters.

Synchronization parameters are used to determine the scope of synchronization, which items has to be synchronized, relate Perfion items to Shopify items, etc. Read more about how synchronization parameters are used in “Overview of Synchronization Process Parameters”.

All Shopify parameters, which are optional can be removed from mappings and Shopify Connector will not send them to Shopify. This means that any existing data in Shopify defined by those not used parameters will not be overwritten by Shopify Connector.

Overview of Synchronization Process Parameters

Some facts about synchronization process and parameters involved, which determine how data will be moved around:

  • Most of configurations for synchronization are controlled from Perfion, but they will be in different areas. The global parameters (ECommerce Settings) will define how synchronization will work for all data and then there will also be other parameters in data entity level (ECommerce Mapping), which will be used to determine how and when different data is synchronized.

  • Individual synchronization parameters in Perfion (ECommerce Mapping) will be related to the actual data, which is synchronized and will allow to control synchronization more precisely in lower (data) level. The data for Shopify synchronization will have product, variant and category data entities. Products and variants will be handled as a single entity, e.g. product will be synchronization item and any product creation, update or deletion will handle all product data including: variants, product images, variant images, product metafields and variant metafields. This means that after changing any product related data, the entire product will be resynchronized. The synchronization will not check individual product data fields and will replace everything with new data from Perfion including image re-upload. The Perfion categories (Shopify custom collections) is also an independent data entity and will be handled separately as synchronization item.

  • Synchronization related parameters used with product and category (custom collection):

    • Synchronization item key (Key) will be used to identify synchronization item in Perfion. The key can be Perfion ID or other unique value and will be used with products and categories.

    • Synchronization item synchronization ID (SyncID) will be used to identify synchronization item in Shopify. The SyncID is Shopify data entity ID and will be used with products and categories. Categories in Shopify are called collections and in this case SyncID will be ID of custom collection. Shopify has also smart collections, but these collections are conceptually different and will not be used with Shopify Connector.

    • Date when synchronization item was last synchronized (SyncDate) will be used to control the age of each synchronization item. The date will be used together with global synchronization parameter DataMaxAgeInMin to determine when each synchronization item must be resynchronized. This parameter will be used with products and categories. Setting this parameter to empty value will be equivalent to telling synchronizer to synchronize this item immediately (e.g. when next synchronization will run).  This parameter will be updated every time the item is synchronized. The parameter will not be updated after synchronization if some serious error happens during synchronization so that synchronization of that failed item can be repeated during next synchronization.

    • Synchronization type of synchronization item (SyncType). This parameter will be used only with product and will determine how individual products will be synchronized. This parameter allows to overwrite the global synchronization parameter for individual products. If parameter is not set, then product will be handled normally. If parameter is set, then based on parameter value product can be ignored in synchronization or product can be synchronized only once. Refer to “Product SyncType Parameter” for more information.

    • Synchronization status information parameter (SyncMsg). This parameter will be used with products and categories. The parameter will show any warning or error messages related to given synchronization item. If item synchronization will fail, then this parameter will show why it happened. The information about synchronization status will be also written to Shopify Connector log file. The full log file cannot be accessed from Perfion, so this parameter allows to understand better what is happening with any synchronization item.

  • Each data entity may have extra synchronization related parameters, which may increase or decrease the scope of data used for synchronization. These Boolean type parameters will determine which parts of each entity will be synchronized.

    • Product: SyncProduct, SyncVariants, SyncDefaultVariant, SyncCollections, SyncMetafields, SyncImages, SyncKeepDeletedMetafields

    • Variant: SyncVariant, SyncMetafields, SyncImage, SyncAllImages

    • Category: SyncCollection, SyncMetafields, SyncKeepDeletedMetafields