---
title: Merchant metafield and cart line properties configuration (optional)
description: Learn how to configure metafields and cart line properties for your tax app.
source_url:
  html: https://shopify.dev/docs/apps/build/tax/onboard/configure-metafields
  md: https://shopify.dev/docs/apps/build/tax/onboard/configure-metafields.md
---

# Merchant metafield and cart line properties configuration (optional)

**Note:**

Shopify's Tax Platform is available by invitation only to select tax software companies integrating with Shopify.

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](https://help.shopify.com/en/manual/custom-data/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](https://github.com/Shopify/extensions-templates/blob/main/tax-calculation/shopify.extension.toml.liquid).

***

## Product 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.

**Note:**

You can update your tax calculation app extension with metafield configuration before setting the metafield data for merchant products/variants. This can be useful when you haven't yet installed your tax app on a store. However, because no metafields for products or variants yet exist, no metafield data is included in the tax calculation API request.

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

***

## Option 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.

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

After [generating your tax calculation app extension](https://shopify.dev/docs/apps/build/tax/build-tax-app#step-1-generate-a-new-tax-app), 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:

```toml
type = "tax_calculation"
name = "my-tax-calculation-extension"


production_api_base_url = "https://production-api.example.com"
benchmark_api_base_url = "https://benchmark-api.example.com"
calculate_taxes_api_endpoint = "api/tax_calculation"


[[metafields]]
namespace="my_tax_app_namespace_1"
key="property_1"


[[metafields]]
namespace="my_tax_app_namespace_1"
key="property_2"


[[metafields]]
namespace="my_tax_app_namespace_2"
key="property_1"
```

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.

### Step 2: Deploy the tax calculation app extension

Follow the instructions on how to [build a tax app](https://shopify.dev/docs/apps/build/tax/build-tax-app) to push and deploy your changes.

**Note:**

If you've already published a "Live" version of your extension, then these steps will vary slightly: you will need to create a new version of your extension and re-publish it to "Live".

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

***

## Option 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](https://shopify.dev/docs/apps/build/custom-data/ownership#app-data-metafields), without having to redeploy your app.

### Step 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:

```toml
type = "tax_calculation"
name = "my-tax-calculation-extension"


production_api_base_url = "https://production-api.example.com"
benchmark_api_base_url = "https://benchmark-api.example.com"
calculate_taxes_api_endpoint = "api/tax_calculation"


[input.metafield_identifiers]
namespace="my_identifier_namespace"
key="my_identifier_key"
```

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.

### Step 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](https://shopify.dev/docs/apps/build/custom-data/ownership#app-data-metafields):

```graphql
query {
  currentAppInstallation {
    id
  }
}
```

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](https://shopify.dev/docs/api/admin-graphql/2024-01/mutations/metafieldsSet) 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.

**Note:**

A combination of 20 product and variant metafields can be specified. Only the first 20 will be used if more than 20 are provided.

Here is an example:

```graphql
mutation CreateAppDataMetafield($metafieldsSetInput: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafieldsSetInput) {
    metafields {
      id
      namespace
      key
      value
    }
    userErrors {
      field
      message
    }
  }
}
```

With variables:

```json
{
  "metafieldsSetInput": [
    {
      "namespace": "my_identifier_namespace",
      "key": "my_identifier_key",
      "type": "json",
      "value": "{\"ProductVariant\":[{\"namespace\":\"namespace_1\",\"key\":\"key_1\"}]}",
      "ownerId": "gid://shopify/AppInstallation/<merchants_installation_id_of_your_app>"
    }
  ]
}
```

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.

***

## Cart line properties

**Note:**

Available as of API version `2026-04`.

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.

### Step 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:

## shopify.extension.toml

```toml
type = "tax_calculation"
name = "my-tax-calculation-extension"


production_api_base_url = "https://production-api.example.com"
benchmark_api_base_url = "https://benchmark-api.example.com"
calculate_taxes_api_endpoint = "api/tax_calculation"


[[cart_line_properties]]
key = "token"


[[cart_line_properties]]
key = "personalization"
```

For a complete example of the extension configuration file, refer to the [tax calculation extension template](https://github.com/Shopify/extensions-templates/blob/main/tax-calculation/shopify.extension.toml.liquid).

### Step 2: Deploy the tax calculation app extension

Follow the instructions on how to [build a tax app](https://shopify.dev/docs/apps/build/tax/build-tax-app) to push and deploy your changes.

**Note:**

If you've already published a "Live" version of your extension, then you need to create a new version of your extension and re-publish it to "Live".

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.

### Example payload

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

```json
{
  "delivery_groups": [{
    "cart_lines": [
      {
        "id": "gid://shopify/CartLine/7",
        "quantity": 1,
        "merchandise": {
          "id": "gid://shopify/ProductVariant/456",
          "title": "Custom T-Shirt"
        },
        "cost": {
          "amount_per_quantity": {
            "currency_code": "USD",
            "amount": "25.00"
          }
        },
        "properties": {
          "token": "abc-123",
          "personalization": "John Smith"
        }
      },
      {
        "id": "gid://shopify/CartLine/6",
        "quantity": 2,
        "merchandise": {
          "id": "gid://shopify/ProductVariant/789",
          "title": "Custom Mug"
        },
        "cost": {
          "amount_per_quantity": {
            "currency_code": "USD",
            "amount": "15.00"
          }
        },
        "properties": {
          "token": "def-456",
          "personalization": "Jane Doe"
        }
      }
    ]
  }]
}
```

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.

***