Note: This is currently a feature in Preview. Please get in touch to get early access.
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 prevent a lot of manual work, we offer a Shopify import/synchronization feature. Our Shopify import will use tags and metafields from Shopify to decide how to create or update products in your Firmhouse project.
This article explains how to initiate an import and also how to tag your Shopify products for appropriate creation in Firmhouse.
Prepare for the import
First add the appropriate tags and metafields to the products in Shopify.
Tags are to set on a product to mark it a subscription or one-off product.
Metafields are for more advanced details. Unless anything changes for a product, this has only to be set up once for a product.
Initiating a product import
In your Firmhouse project go to Apps in the sidebar.
Click Configure on the Shopify app.
Scroll down and find the Sync settings and Fields to update sections. The various options are documented below in this article.
Click Sync products.
The import will appear in the overview below.
After the import finished, click show changes to view the records that were updated. The show changes button will not appear if no changes were made.
Choose tags based on your project type
To have the Shopify import pick up products from your Shopify store and import them into Firmhouse, you can use tags. In the following overview you will find a list of tags that you can add on your Shopify products and what they do in Firmhouse.
In case you have multiple Shopify product Variants, it's only possible to use metafields and not the tags. See below for a solution to that.
Within Firmhouse there are two different project types. Make sure you use the correct tags and metafields below.
Tags overview for Plan based projects
On the Shopify products add one of the following tags:
FIRMHOUSE_ONE_TIME - The product will be created as a one-time sales product in Firmhouse, taking the price of the Shopify product or variant as price.
FIRMHOUSE_SUBSCRIPTION - The product will be created as monthly/recurring product in Firmhouse. The price is taken from the firmhouse.subscription_price metafield. If the metafield does not exist, the Shopify product or variant's price is used.
If you combine multiple tags on a single Shopify product, then multiple products are created in Firmhouse. This allows you sell a single Shopify products via different sales options in Firmhouse.
Tags overview for Smart order based projects
There are two possible Shopify tag variants that could be used here: "FIRMHOUSE_SHIPMENT_ONE_TIME" and "FIRMHOUSE_SHIPMENT_INTERVAL_<number>_<unit>". These tags will define what shipment settings products have.
In the case of the first tag, it will be shipping once. The second tag is dynamic so customers can put any shipment interval and unit in it. For example, "FIRMHOUSE_SHIPMENT_INTERVAL_2_WEEKS" will set a shipment schedule to every two weeks.
Note that that the <unit> part is always plural (even for 1_WEEKS).
The checkbox for that setting in the UI is "Shipping settings of the product".
Metafields on plan based projects
The firmhouse.subscription_price metafield
For certain tags we look at the firmhouse.subscription_price metafield on your Shopify product or variant to import the price into Firmhouse. So by defining a metafield you can have a different price for your one-time sales products compared to your subscription products.
The metafield we use is firmhouse.subscription_price. This metafield needs to be defined as a Number-type in your Shopify catalog. This metafield is currently only used for products with the FIRMHOUSE_SUBSCRIPTION tag.
Metafields on smart order based projects
To customize the price of synced products, set the metafield "firmhouse.price" on Shopify product variant. In case it was set we'll ignore the Shopify product price field and take the price right from the metafield. This will only work for recurring products.
In the metafield definition "firmhouse" is the namespace, "price" is the name of the key. The value type for the price could be Integer or Decimal.
More detailed Metafields options
For Shopify Product Variants it's not possible to add tags, so we added support for two new Shopify Product variable metafields: firmhouse.shipment and firmhouse.billing.
firmhouse.billing is for setting price type for imported products. It can obtain two values: one_time or subscription and it will set product type according to that value. As with tags it only works for Plan based projects.
firmhouse.shipment is for setting logistics settings for imported products. It can be set as one_time or as flexible metafield similar to tags in form of <amount>_<unit>.
For example 2_months or 3_days. The script will set appropriate logistic settings according to the metafield value. This shipment metafield only works for smart order based projects.
For both metafields to work the default setting "Only create new products from Shopify tags and skip Shopify products without any tags" has to be disabled. Otherwise, during synchronization only products with tags will be synced.
"Shipping settings of the product" or/and "Billing settings of the product" settings should be enabled.
Metafields for commitment terms
These metafields for commitment terms will only work with plan-based projects.
There are three metafields that can be set on Product variables in Shopify: max_commitment, min_commitment and grace_period. The values could be flexible and follow the pattern <amount>_<unit> similar to tags and other metafields.
firmhouse.max_commitment format: <amount>_months|years
firmhouse.min_commitment format: <amount>_days|weeks|months|years
firmhouse.grace_period format: <amount>_days|weeks|months|years
The important note here for all similar tags/metafields they don't support singular forms. So it should be 1_days or 1_years.
The following options are available within Firmhouse for the Shopify product sync
Firmhouse Tags are upper case and the metafields lowercase
More info on how to create a metafield in Shopify, see the Shopify helpdesk.