Note: This is currently a feature in Preview. Please let us know if you experience difficulties.
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, we offer a Shopify import/synchronization feature. Normally, Shopify products don't contain information about subscriptions, e.g. billing schedule. We use 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 some information about how a product should appear in Firmhouse. They can be used both for creating, 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 - 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
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
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 that the <UNITS> part in tags is plural and capitalized (e.g. 1_WEEKS).
There is one tag, which can be applied to both project types:
FIRMHOUSE_SUBSCRIPTION_DISCOUNT_<number>- applies a discount % to products with recurring shipping, which were created viaFIRMHOUSE_SHIPMENT_INTERVALor theshipmentmetafield. Product with one-time shipping will not be affected even if they have recurrent billing.
Tips and examples for tags
If a tag is applied to a Shopify product with multiple variants, the setting will be applied to all variants (can be overriden 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. In the same example, if the Shopify product has variants, two Firmhouse products will be created for each variant.
Example:
Imagine you run a store that sells cat food. You want to offer a pack of food as a one-time purchase for €100 or as a monthly subscription for €95/month. You create a product in Shopify with the following tags:
This way, from a single Shopify product, you can create two Firmhouse products, and the recurring one has a lower price.
💡 This example uses a Smart order-based project, but the same result can be achieved in a Plan-based project with a metafield for the shipment interval.
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 - 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. This means it will be visible in products and variants and you can directly set a value for it.
The following metafields are available:
Key | Type & | Example | Limitations |
shipment | Singe line text |
| - |
subscription_price | Decimal |
| Affects only recurring products |
subscription_discount | Integer |
| Affects only recurring products |
exclude_from_discount | Singe line text |
| Accepts only |
billing | Singe line text |
| Works only in plan-based projects |
max_commitment | Singe line text
|
| Works only in plan-based projects |
min_commitment | Singe line text
|
| Works only in plan-based projects |
grace_period | Singe line text
|
| Works only in plan-based projects |
💡 Note that that the <units> part in metafields is plural and not capitalized (e.g. 1_weeks).
Tips and examples for 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.
⚠️ Do not use tags and metafields with overlapping functions simultaneously. This can lead to new products being created every time you sync.
Let's say 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 and because metafields take priority, a shipment interval of 2 months. If there are multiple variants in the product, a new Firmhouse product will be created for each variant.
Example:
Imagine you run a store that sells cat food. You offer packs of food in two sizes - 10kg for €100 and 5kg for €60. You want to offer each size as a one-time purchase and as a subscription with a 5% discount. To do this, you can create a product in Shopify with the following settings:
Sizes:
Tags:
Metafields:
This way, from a single Shopify product with two variants, you can create four Firmhouse products, and the two recurring ones have a lower price. If you would rather set a price manually, you can also use the subscription_price metafield. Note that if you use subscription_price on the product, it will apply to both sizes. If you want a different subscription_price for each size, you will need to set it for each variant.
Performing a product import or sync
Follow these steps to configure and perform a product import or sync:
In your Firmhouse project, go to Apps.
Click Configure on the Shopify app.
Click on the Product sync tab.
Under Sync settings, select the desired options in the How to sync and What to sync sections.
Click on Start syncing.
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 settings
The following sync settings are available:
We recommend to select only the ones you need for a specific import.