Skip to content

Shopify Dude Fix

Shopify Tax Managed Mode Breaks API Writes? Stop Overriding the Settings Shopify Now Owns

Shopify Tax managed mode can now reject or rewrite Admin API requests that conflict with required US tax behavior. Fix Markets writes, product publishing, and custom line-item tax logic before adopting 2027-01.

Quick answer: Shopify Tax managed mode now owns more of the tax behavior for US sales. If an app tries to override settings that managed mode controls, Admin API writes can fail with validation errors or be adjusted by Shopify. The safest pattern is to stop sending fields you do not need to control, use Shopify’s required defaults where you do, and replace custom-line-item taxable flags with productCategoryId when moving to API version 2027-01.
On this page

What changed

On October 28, 2026, Shopify announced managed mode for Shopify Tax. The important developer change is not simply that Shopify Tax has a new setting. Managed mode changes what apps are allowed to write when a store uses Shopify Tax for US sales.

Shopify now validates certain Admin API requests against tax behavior that managed mode is responsible for keeping consistent. Requests that already follow those rules—or that omit settings the app does not need to manage—continue to work. Requests that try to override managed-mode requirements can return validation errors.

The current changes affect four areas: Markets API writes, product publishing, custom line-item taxation, and checkout footer visibility behavior.

Markets writes can now fail when they conflict with US tax requirements

For merchant-managed, non-retail markets that include the United States, marketCreate and marketUpdate now validate currency and tax-display settings when the store uses Shopify Tax managed mode.

The easiest fix is often subtraction. If your app does not actually need to own currencySettings or priceInclusions, stop sending them.

For a US-only market, Shopify documents the required defaults as:

{
  "currencySettings": {
    "baseCurrency": "USD",
    "localCurrencies": false
  },
  "priceInclusions": {
    "taxPricingStrategy": "ADD_TAXES_AT_CHECKOUT"
  }
}

For a market that includes the United States and another country, such as Canada, the required pattern changes:

{
  "currencySettings": {
    "localCurrencies": true
  },
  "priceInclusions": {
    "taxPricingStrategy": "INCLUDES_TAXES_IN_PRICE_BASED_ON_COUNTRY"
  }
}

If a mutation violates the managed-mode rules, inspect userErrors.code, userErrors.field, and userErrors.message. Shopify documents UNSUPPORTED_CURRENCY for currency violations and INCOMPATIBLE_CONFIGURATION for tax-display violations on API version 2026-07 and later.

Product publishing now has a Shop dependency

Managed mode also tightens the relationship between Shop and several dependent sales channels.

Products published to Online Store, Headless, Hydrogen, or Buy Button must also be published to Shop. If your integration publishes or unpublishes products independently across channels, this is the part most likely to surprise you.

On dated API versions, Shopify may automatically adjust a request so the resulting publication state satisfies the requirement. For example, publishing to a dependent channel can also add Shop. Removing Shop can also remove dependent-channel publications.

On unstable, conflicting requests can fail instead.

The practical fix is to make the relationship explicit. If your app publishes to Online Store, Headless, Hydrogen, or Buy Button, include Shop in the same operation or publish to Shop first. If your app removes a product from Shop, remove the dependent channels in the same change or beforehand.

Do not rely on silent correction as your business logic. A dated API version may currently repair the request for you, but your integration should still understand the intended publication state.

Custom line items should use product categories, not just taxable true or false

The old boolean model is becoming less authoritative.

For custom line items in draft orders and order edits, Shopify is deprecating the taxable input in favor of productCategoryId on API version 2027-01 and later.

For stores using Shopify Tax managed mode, taxable is ignored on custom line items in every API version. The product category determines the item’s tax treatment. A custom line item with no category is treated as Uncategorized and taxed at the standard rate.

That means code like this:

{
  "title": "Custom service",
  "originalUnitPrice": "25.00",
  "quantity": 1,
  "taxable": false
}

is no longer a reliable way to define tax treatment on a managed-mode store.

Instead, look up the appropriate category from Shopify’s Standard Product Taxonomy and pass its ID as productCategoryId. Shopify exposes the taxonomy through GraphQL:

query {
  taxonomy {
    categories(search: "t-shirts", first: 5) {
      nodes {
        id
        fullName
      }
    }
  }
}

Then use the returned taxonomy category ID when creating or editing the custom line item. If the ID is not valid in the current taxonomy, Shopify returns a user error.

Do not use a category as a substitute for customer-level tax exemption

There are two different kinds of tax decisions here.

If a specific item should receive category-specific tax treatment, use the product category. If the entire draft order should be tax-exempt because of the buyer, use the tax-exempt status on the customer, company, or company location.

That distinction matters especially for B2B and ERP-generated draft orders. Moving every tax decision onto the line item can produce incorrect results when the exemption actually belongs to the buyer.

Shopify also clarified that checkout branding footer visibility controls only merchant-configurable footer content. Shopify-provided transaction information can still appear even when merchant footer content is set to hidden.

If your app generates checkout-branding previews or visual regression tests, do not assume HIDDEN means a completely empty footer.

Common misunderstanding: “Managed mode is just a merchant-side tax setting, so my integration does not need to change.” It can directly change API behavior. An app that writes Markets settings, publishes products across channels, creates custom line items, or previews checkout branding can see different validation or resulting state when the store uses Shopify Tax managed mode.

How to test this

  1. Use a development or test store with Shopify Tax managed mode enabled for US sales.
  2. Replay your existing marketCreate and marketUpdate calls. Record which requests send currencySettings or priceInclusions unnecessarily.
  3. Test one request with managed-mode-compatible settings and one deliberately incompatible request. Verify your integration surfaces userErrors instead of retrying the same mutation indefinitely.
  4. Publish a product to each channel your integration manages and inspect the resulting Shop publication state.
  5. Test unpublishing from Shop while the product remains on a dependent channel and confirm your code handles Shopify’s resulting behavior.
  6. Create a draft order custom line item with your old taxable logic, then repeat using productCategoryId. Compare calculated taxes.
  7. Test a tax-exempt customer or B2B company location separately so buyer-level exemption is not confused with product-category treatment.
  8. If your app manages checkout branding, render a footer with merchant content hidden and confirm your visual tests allow Shopify-provided transaction information to remain visible.