Importing and Syncing Products

If you have a large product catalog on Shopify it will be quite some work to manually create and link all these products to their counterpart in Firmhouse. To save you time and manual work, Firmhouse offers a Shopify import/synchronization feature.

Normally, Shopify products don't contain information about subscriptions, such as billing schedule. Firmhouse uses tags and metafields in Shopify to provide this information and create or update the products correctly in Firmhouse. This article explains how to add tags and metafields to your product and initiate an import.

Understanding tags and metafields

Tags and metafields are used to provide information about how a product should appear in Firmhouse. They can be used both for creating new products as well as for updating existing products.

Tags

In Shopify, tags are used to categorize a variety of objects. In this article we'll focus only on product tags but you can read about other uses in Shopify's article on Creating and using tags in Shopify.

Most tags are valid only for specific project types (Plan-based or Smart order-based).

Tags for Plan-based projects

The following tags work with Plan-based projects:

• FIRMHOUSE_ONE_TIME - creates a one-time sale product in Firmhouse

• FIRMHOUSE_SUBSCRIPTION - creates a monthly/recurring product in Firmhouse

Tags for Smart-order-based projects

The following tags work with Smart order-based projects:

• FIRMHOUSE_SHIPMENT_ONE_TIME - creates a product that will be shipped only once

• FIRMHOUSE_SHIPMENT_INTERVAL_<number>_<UNITS> - creates a recurring product that will be shipped according to the specified interval (note that the <UNITS> part is plural and capitalized, e.g., 1_WEEKS)

• FIRMHOUSE_SHIPMENT_ON_BILLING_CYCLE - creates a recurring product that aligns with the subscriber's unified shipment schedule (only relevant for setups where all recurring products are shipped together)

Tags for both project types

The following tags can be applied to both project types:

• FIRMHOUSE_SUBSCRIPTION_DISCOUNT_<number> - applies a discount percentage to products with recurring shipping created via FIRMHOUSE_SHIPMENT_INTERVAL or the shipment metafield (products with one-time shipping will not be affected)

• FIRMHOUSE_SHOPIFY_PRICE_FOR_ONE_TIME - the price of the product or variant in Shopify will be used for one-time products, overriding the subscription_price metafield (use this tag together with the metafield to set different prices for one-time and recurring products)

Tips for using tags

If a tag is applied to a Shopify product with multiple variants, the setting will be applied to all variants (can be overridden by variant metafields).

If multiple tags for shipment or billing are applied to a Shopify product, this will create multiple Firmhouse products. For example, adding both FIRMHOUSE_SHIPMENT_ONE_TIME and FIRMHOUSE_SHIPMENT_INTERVAL_1_MONTHS to a product will create a one-time product and a recurring product. If the Shopify product has variants, two Firmhouse products will be created for each variant.

Metafields

Just like tags, metafields can be added to many kinds of objects. In this article we'll focus on product and variant metafields. You can read about other uses in Shopify's article on Metafields. First, learn how to create custom metafield definitions.

All metafields used by Firmhouse use the firmhouse namespace. After you create a metafield, it will be "pinned" by default, meaning it will be visible in products and variants and you can directly set a value for it.

The following metafields are available:

Key	Type & Accepted values	Example	Details & limitations
shipment	Single line text <amount>_<units>	1_weeks	-
subscription_price	Decimal	21.50	Affects all types of products
subscription_discount	Integer	50	Affects only recurring products
exclude_from_discount	Single line text true	true	Accepts only true. Setting it to false will not make the product eligible for discount if it was previously excluded.
billing	Single line text one_time or subscription	one_time	Works only in plan-based projects
max_commitment	Single line text <amount>_<units>	2_years	Works only in plan-based projects
min_commitment	Single line text <amount>_<units>	3_months	Works only in plan-based projects
grace_period	Single line text <amount>_<units>	14_days	Works only in plan-based projects

Note that the <units> part in metafields is plural and not capitalized (e.g., 1_weeks).

Tips for using metafields

Metafields can be applied to both products and variants. If the same metafield is applied to a product and a variant at the same time, the value of the variant metafield will take priority.

Metafields override tags. If you add a FIRMHOUSE_SUBSCRIPTION_DISCOUNT tag and a subscription_discount metafield simultaneously, the metafield will take priority. There's one exception to this: FIRMHOUSE_SHOPIFY_PRICE_FOR_ONE_TIME overrides metafields.

Do not use tags and metafields that set product schedules simultaneously. This can lead to new products being created every time you sync. For example, if you have a Smart order-based project and you add the tag FIRMHOUSE_SHIPMENT_1_WEEKS and the metafield shipment with value 2_months, every time you sync a new Firmhouse product will be created because metafields take priority.

Performing a product import or sync

Steps

1. In your Firmhouse project, go to Apps.

2. Click Configure on the Shopify app.

3. Click on the Product sync tab.

4. Under Sync settings, select the desired options in the How to sync and What to sync sections.

5. Click on Start syncing.

6. A summary of the sync will be shown in the Sync History below. Here, you can view the changes and settings for a specific synchronization.

Sync History showing completed synchronizations

Sync settings

The following sync settings are available:

Sync settings showing How to sync and What to sync options

How to sync options include creating new products, skipping products without Shopify tags, updating existing products, deleting products without Shopify tags, grouping and updating Shopify variants, and creating an asset for every product.

What to sync options include product image, product title, product price, product SKU, product tax rate, shipping settings of the product, billing settings of the product, and commitment terms of the product.

We recommend selecting only the options you need for a specific import.