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.
Checkout footer visibility is also more limited than some apps assume
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.
How to test this
- Use a development or test store with Shopify Tax managed mode enabled for US sales.
- Replay your existing
marketCreateandmarketUpdatecalls. Record which requests sendcurrencySettingsorpriceInclusionsunnecessarily. - Test one request with managed-mode-compatible settings and one deliberately incompatible request. Verify your integration surfaces
userErrorsinstead of retrying the same mutation indefinitely. - Publish a product to each channel your integration manages and inspect the resulting Shop publication state.
- Test unpublishing from Shop while the product remains on a dependent channel and confirm your code handles Shopify’s resulting behavior.
- Create a draft order custom line item with your old
taxablelogic, then repeat usingproductCategoryId. Compare calculated taxes. - Test a tax-exempt customer or B2B company location separately so buyer-level exemption is not confused with product-category treatment.
- 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.
Sources and further reading
- Shopify developer changelog: Managed mode for Shopify Tax
- Shopify Admin GraphQL: DraftOrderLineItemInput
- Shopify Admin GraphQL: taxonomy query
- Shopify Admin GraphQL: publishablePublish
Documentation reviewed October 28, 2026.

