Merchant metafield and cart line properties configuration (optional)

This process is optional. You can skip the following steps if you don't need to receive product/variant metafields or cart line properties as part of the tax calculation request.

The Tax Platform supports two types of optional custom data in tax calculation requests:

• Product and variant metafields: Custom data configured on a merchant's products and product variants. Learn more about metafields.
• Cart line properties: Custom name-value pairs on individual cart line items, such as personalization text or gift wrap options.

You can configure either or both of these in your tax calculation app extension configuration.

Anchor to Product and variant metafieldsProduct and variant metafields

Once a merchant has installed your tax app on their store, and metafields on products and variants have been created, you can configure your tax calculation app extension to reference these metafields to include them in the tax calculation request payload.

Here are a few things to keep in mind regarding metafields for a merchant's store:

• Only metafields added to products and variants can be passed through in the Tax Calculation API.

• The max length for a metafield key is 30 characters.

• The max length for a metafield namespace is 20 characters.

• Metafield values are restricted to a length of 1,000 characters. Values longer than this are truncated in the Tax Calculation API request body.

• The metafield data appears in the metafields field of the ProductVariant and Product objects in the Tax Calculation API.

Once metafields have been added to a shop's products and variants, you're ready to update the tax calculation app extension to specify which metafields you'd like forwarded to your tax app during tax calculations. The following instructions guide you through this.

Shopify provides two methods that allow you to specify which product and variant metafields your tax app uses during tax calculations:

Anchor to Option 1: Static list of metafield referencesOption 1: Static list of metafield references

This option provides an easy way to specify a select set of metafields directly inside your tax calculation app extension.

Anchor to Step 1: Update the tax calculation configuration file to specify metafieldsStep 1: Update the tax calculation configuration file to specify metafields

After generating your tax calculation app extension, a shopify.ui.extension.toml file was generated for you to set up the details of your tax app. Using this file, you can specify a list of up to 10 metafield namespace/keys which your tax app will receive during tax calculations:

Using the example above, any metafields on a store's products or variants matching the namespace and keys of the 3 specified will be included in the tax calculation API request payload your tax app will receive.

Anchor to Step 2: Deploy the tax calculation app extensionStep 2: Deploy the tax calculation app extension

Follow the instructions on how to build a tax app to push and deploy your changes.

After publishing your tax calculation app extension containing the newly specified metafields, any future tax calculation API requests will now contain metafield data.

Anchor to Option 2: Dynamically configured metafield references per shopOption 2: Dynamically configured metafield references per shop

With this option, you can dynamically create and change lists of metafield references per merchant by using app-data metafields, without having to redeploy your app.

Anchor to Step 1: Update the Tax Calculation configuration file to specify your app-data metafield referenceStep 1: Update the Tax Calculation configuration file to specify your app-data metafield reference

Create a new metafield identifier field in shopify.ui.extension.toml using the following syntax:

This new field indicates to Shopify where to look for your app-data metafields containing merchant metafield references. You are free to choose whatever namespace/key pair you'd like, but be sure to references these same ones while creating your merchant specific app-data metafields in the next step.

Anchor to Step 2: Create app-data metafields which contain merchant dataStep 2: Create app-data metafields which contain merchant data

To find your app's installation_id for a merchant's store, use the following GraphQL query, as described in App data metafields:

After retrieving the AppInstallation ID, you can now configure targeted merchant-specific metafields using the namespace and key pairs you want Shopify to query for during tax calculations. Follow these instructions to set up an app-data metafield, specifying the metafields you'd like to target in the app-data metafield value. Be sure to use the same namespace/key pair you chose in Step 1 as the namespace/key for this new metafield.

Here is an example:

With variables:

After setting this app-data metafield with your tax app, tax calculation API requests now contain the targeted metafields requested in your app-data metafield value. You can also change the targeted metafields anytime using this GraphQL query without having to redeploy your app.

Anchor to Cart line propertiesCart line properties

Cart line properties are custom name-value pairs that merchants add to individual line items, such as personalization text, tokens, or gift wrap options. You can configure your tax calculation app extension to receive specific cart line property keys in tax calculation requests.

The property key limit applies to which keys your app wants to receive, not the number of line items. For example, if you configure two keys (token and personalization) and the cart has 10 line items, all 10 line items include their token and personalization values if present.

Anchor to Step 1: Update the tax calculation configuration file to specify cart line property keysStep 1: Update the tax calculation configuration file to specify cart line property keys

In your shopify.extension.toml file, add [[cart_line_properties]] entries for each property key you want to receive. You can specify a maximum of five keys:

For a complete example of the extension configuration file, refer to the tax calculation extension template.

Anchor to Step 2: Deploy the tax calculation app extensionStep 2: Deploy the tax calculation app extension

Follow the instructions on how to build a tax app to push and deploy your changes.

After publishing your tax calculation app extension containing the configured cart line property keys, future tax calculation API requests include property data in the delivery_groups[].cart_lines[].properties field for each line item.

Anchor to Example payloadExample payload

With token and personalization configured, a tax calculation request includes the following cart line data:

Only the property keys you configured are included. If a line item doesn't have a value for a configured key, that key is omitted from the properties object for that line item.