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).
FIRMHOUSE_SHIPMENT_ON_BILLING_CYCLE- creates a recurring product that aligns with the subscriber's unified shipment schedule. Please note, it's only relevant for setups where all recurring products are shipped together. Feel free to reach out if you're interested in exploring how this could work for your business!
Tags, 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.FIRMHOUSE_SHOPIFY_PRICE_FOR_ONE_TIME- the price of the product or variant in Shopify will be used for one-time products, overriding thesubscription_pricemetafield. The tag and metafield are used together to set different prices for one-time and recurring products.
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 - set lower price for recurring shipments with tags
Example - set lower price for recurring shipments with tags
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 | Details & limitations |
shipment | Singe line text |
| - |
subscription_price | Decimal |
| Affects all types of 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. 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.
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, the shipment interval will be 2 months. If there are multiple variants in the product, a new Firmhouse product will be created for each variant.
Example - set lower price for recurring shipments with metafields
Example - set lower price for recurring shipments with metafields
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 will 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.
Example - set prices for one-time and rental products
Example - set prices for one-time and rental products
Imagine you run a store, which offers furniture for rent. You want to let your customers buy your products directly as a one-time purchase. You can control the prices for both products (one-time and rental) from Shopify. To do this, create a product in Shopify with the following settings:
Variants:
Tags:
Metafields:
This way, from a single Shopify product with two variants, you can create four Firmhouse products. The one-time purchase products will have a price of €200 and the rental product (one-time shipping, recurring billing) will have a recurring price of €15.
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.