> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firmhouse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Restrict checkout options with Shopify variant metafields

> Use Firmhouse variant metafields to require a subscription, require a one-time purchase, or allow only specific Shopify selling plans.

The Firmhouse **Cart and checkout validation** rule can restrict how each Shopify product variant is purchased. The rule checks metafields on every variant in the cart and blocks checkout when the selected purchase option is not allowed.

This is useful when you do not want to use Shopify's product-wide setting to require a selling plan for every variant, but need to restrict only some variants. Firmhouse lets you apply validation to individual variants while leaving the other variants unrestricted.

## Available metafields

Create the following metafields as **Product variant** definitions in Shopify. The namespace is `firmhouse`.

| Namespace and key                  | Recommended type                | When set                                  | Result                                                                                                  |
| ---------------------------------- | ------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `firmhouse.requires_subscription`  | True or false                   | `true`                                    | Blocks a one-time purchase. The variant must have a selling plan.                                       |
| `firmhouse.requires_otp`           | True or false                   | `true`                                    | Blocks a subscription purchase. The variant must be bought as a one-time purchase.                      |
| `firmhouse.requires_selling_plans` | List of single-line text values | One or more full Shopify selling plan IDs | When the variant is bought as a subscription, blocks any selected selling plan that is not in the list. |

An unset metafield does not add a restriction. `firmhouse.requires_selling_plans` does not by itself require a subscription; combine it with `firmhouse.requires_subscription` when a variant must be a subscription and only specific selling plans are allowed.

Do not set both `firmhouse.requires_subscription` and `firmhouse.requires_otp` to `true` on the same variant. One blocks one-time purchases and the other blocks subscription purchases, leaving no valid purchase option.

<Note>
  Metafields must be defined for **Variants**, not Products. The validation reads the selected variant's values.
</Note>

## Create the metafield definitions

1. In Shopify admin, go to **Settings > Metafields and metaobjects**.
2. In the **Metafields** section, select **Variants**.
3. Click **Add definition**.
4. Enter a descriptive name, such as `Requires subscription`.
5. Change **Namespace and key** to the exact value from the table, such as `firmhouse.requires_subscription`.
6. Select the recommended type from the table.
7. Click **Save**.
8. Repeat these steps for each restriction you need.

For `firmhouse.requires_selling_plans`, choose **Single line text**, then change **One value** to **List of values**. Add each allowed selling plan as its full Shopify global ID, for example `gid://shopify/SellingPlan/1234567890`.

## Set restrictions on a variant

1. In Shopify admin, go to **Products** and open the product.
2. Open the variant you want to restrict.
3. In the **Metafields** section, set the applicable Firmhouse values.
4. Click **Save**.

Repeat this for every variant that needs a restriction. If a product has several variants, values set on one variant do not apply to the others.

## Turn on the checkout rule

1. In Shopify admin, go to **Settings > Checkout**.
2. In **Checkout rules**, click **Add rule**.
3. Select the Firmhouse **Cart and checkout validation** rule.
4. Save the rule, then click **Turn on**.

The rule must be turned on before the metafields affect the cart or checkout.

## Test the validation

Test each configured variant in your storefront:

* For `firmhouse.requires_subscription`, try adding the variant without a selling plan. Checkout should be blocked.
* For `firmhouse.requires_otp`, try adding the variant with a selling plan. Checkout should be blocked.
* For `firmhouse.requires_selling_plans`, try one allowed and one unlisted selling plan. Only the unlisted plan should be blocked.

The error includes the product and variant title. Firmhouse uses the checkout language for supported translations and falls back to English for other languages.

## Troubleshooting

If checkout is not blocked, check that:

* the checkout rule is turned on in Shopify;
* the metafield definition belongs to **Variants**;
* the namespace and key match the table exactly;
* the metafield value is set on the variant being added to the cart; and
* every entry in `firmhouse.requires_selling_plans` is a full selling plan ID, not a selling plan group ID or display name.

## Related articles

* [Shopify app settings](/configure/shopify/shopify)
* [Shopify selling plans and selling plan groups](/shopify/selling-plans-and-groups)
* [Create custom metafield definitions in Shopify](https://help.shopify.com/en/manual/custom-data/metafields/metafield-definitions/creating-custom-metafield-definitions)
* [Configure Shopify checkout rules](https://help.shopify.com/en/manual/checkout-settings/checkout-customization)