Tax summary webhook and calculation requests now include customer and company metafields

As of API version 2026-04, tax calculation requests for tax partner apps now include buyer metafields. These fields provide custom data associated with customers (for D2C orders) and companies (for B2B orders) that may affect tax calculations. This enhancement allows tax partners to access merchant-defined buyer attributes for more accurate tax determination and compliance reporting.

What's new

The tax calculation request payload now includes new metafields arrays in the buyer identity section:

1. Customer metafields (cart.buyer_identity.customer.metafields[]):

   • Available for D2C orders
   • Contains custom attributes defined by the merchant for individual customers
   • Examples include prescription status, tax exemption certificates, and customer classifications

2. Company metafields (cart.buyer_identity.purchasing_company.company.metafields[]):

   • Available for B2B orders
   • Contains custom attributes defined by the merchant for business customers
   • Examples include wholesale status, resale certificates, and business classifications

Metafield structure

Each metafield contains information on namespace, key, type, and value. The following example shows the structure before and after the update:

Customer metafields

Before (2026-01 and earlier):

{
  "customer": {
    "id": "123",
    "exemptions": []
  }
}

After (2026-01):

{
  "customer": {
    "id": "123",
    "exemptions": [],
    "metafields": [
      {
        "namespace": "custom",
        "key": "has_prescription",
        "type": "boolean",
        "value": "true"
      }
    ]
  }
}

Company metafields

Before (2026-01 and earlier):

{
  "purchasing_company": {
    "company": {
      "id": "456",
      "external_id": "ACME-001"
    },
    "company_location": {
      "id": "789",
      "external_id": "ACME-LOCATION-001"
    }
  }
}

After (2026-04):

{
  "purchasing_company": {
    "company": {
      "id": "456",
      "external_id": "ACME-001",
      "metafields": [
        {
          "namespace": "custom",
          "key": "customer_class",
          "type": "single_line_text_field",
          "value": "wholesale"
        }
      ]
    },
    "company_location": {
      "id": "789",
      "external_id": "ACME-LOCATION-001"
    }
  }
}