Managed mode for Shopify Tax: what changes for Admin API writes
Shopify Tax managed mode makes some Admin API writes fail validation: markets, product publishing and custom line items. Checkout footer behaviour is also clarified.

- Published
- 15 Nov 2026
- API version
- 2027-01
- Affects
- GraphQL Admin API, Admin REST API
What changed
Shopify announced changes to Admin API behaviour for Shopify Tax managed mode on 28 October 2026. Managed mode lets Shopify apply the correct tax behaviour for US sales by managing some store settings and API behaviour directly. To keep those settings consistent, some Admin API writes now validate against the requirements of managed mode.
Requests that already use the required settings, or that omit settings the app doesn't need to manage, continue to work. Requests that try to override managed-mode requirements might now return validation errors. In some cases, tax behaviour now depends on more specific product or store data instead of simple boolean settings.
The changes fall into four categories:
Breaking changes: Markets API writes and product publishing writes can now fail when they conflict with managed mode requirements.
Deprecation: the
taxableinput on custom line items is deprecated in favour ofproductCategoryId.New capability: apps can assign product categories to custom line items in draft orders and order edits.
Behaviour clarification: checkout footer visibility controls merchant-configurable content only, not Shopify-provided transaction information.
These changes affect apps that configure markets, publish products, create custom line items, or preview checkout branding for stores that use Shopify Tax managed mode. Stores that don't use managed mode are unaffected by the validation changes, even if they sell to US customers. The sections below cover each change in detail.
Markets: required US defaults
For stores that use Shopify Tax in managed mode for US sales, marketCreate and marketUpdate now reject attempts to override the required currency and tax-display defaults. The validation applies only to merchant-managed, non-retail markets that include the United States. Markets without the United States, retail markets and third-party-managed markets are excluded. Stores that don't use managed mode are unaffected, even if they sell to US customers.
The change applies across all supported API versions, including unstable. It only applies when a request supplies currencySettings or priceInclusions. Requests that omit both are unchanged. When either input is submitted, Shopify validates the resulting setting, including retained values and the defaults for omitted subfields.
Required values
For a US-only market, use these values:
{
"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, use these values:
{
"currencySettings": {
"localCurrencies": true
},
"priceInclusions": {
"taxPricingStrategy": "INCLUDES_TAXES_IN_PRICE_BASED_ON_COUNTRY"
}
}If your app sets these fields, use the required values, or omit the fields your app doesn't need to manage.
Handling errors
Handle failures through userErrors.code, userErrors.field and userErrors.message. The codes are:
Currency violations return
UNSUPPORTED_CURRENCY.Tax-display violations return
INCOMPATIBLE_CONFIGURATIONon API version2026-07and later, andGENERIC_ERRORon earlier versions.
Product publishing requires the Shop channel
For stores that use Shopify Tax managed mode, a product on Online Store, Headless, Hydrogen or Buy Button must also be published to Shop. These four channels depend on Shop. Stores that don't use managed mode are unaffected, and so are requests that only change other sales channels, collections or product variants. The change is rolling out gradually to managed-mode stores. There are no schema changes.
How the API version changes the result
unstable: a request that would leave a product on a dependent channel without Shop fails.Dated versions: Shopify applies the same rules but changes the request so it complies, then saves it.
Shopify doesn't save any part of a failed request. A product counts as being on a channel when it is published there, scheduled to publish there, or, for draft products, added to that channel. A request that includes both Shop and a dependent channel is checked as a whole, in any order.
Affected requests
GraphQL:
publishablePublish,publishableUnpublishandpublicationUpdate.Deprecated GraphQL publishing APIs:
productPublish,productUnpublish, and the publishing fields onproductCreateandproductUpdate. The two mutations follow the same failure conditions aspublishablePublishandpublishableUnpublish.REST Admin API: product create and update requests fail when they would put a product on Online Store while the product isn't on Shop or is blocked by Shop.
Validation rules
Shop blocks a product when it rejects the product or flags it as needing action.
publishablePublishfails if Shop blocks the product and the resulting state leaves it on a dependent channel, even if the request publishes only to Shop.productUpdatefails in the same case.Removing a product from Shop requires removing its dependent-channel publications, in any state. This applies to
publishableUnpublishand topublicationUpdateremovals from Shop.publicationUpdate: adding a product to a dependent channel fails if the product isn't on Shop or Shop blocks it. Adding a blocked product to Shop also fails if it remains on a dependent channel. Products already in the target publication aren't checked when included inpublishablesToAdd.publicationUpdaterejectsautoPublish: trueon a dependent channel when Shop's publication doesn't auto-publish. It also rejectsautoPublish: falseon Shop when a dependent channel still auto-publishes.productUpdate: publications replace the product's entire publication list. Include Shop whenever the replacement list includes a dependent channel, even if the product is already on Shop. When the request also changes status, validation uses the new status.
What dated versions change for you
Publishing to a dependent channel also publishes to Shop. Shop doesn't support scheduled publishing, so Shop is published immediately, even when the dependent channel is scheduled.
Removing a product from Shop also removes it from its dependent channels.
On
productCreateandproductUpdate, Shop is added when the request puts the product on a dependent channel. OnproductUpdate, a publications list that leaves out Shop keeps the product on Shop.For
publicationUpdate, adding products to a dependent channel also adds them to Shop, and removing products from Shop removes them from dependent channels. Turning onautoPublishfor a dependent channel turns it on for Shop; turning it off for Shop turns it off for dependent channels.A Shop rejection or a needs-action flag doesn't block the request.
REST Admin API product, product listing and product publication requests behave the same way.
If the request still breaks the rules after these changes, it fails with the same error as in unstable. For example, this happens when a draft product is scheduled on a dependent channel without Shop.
What to do
If your app publishes to a dependent channel, publish to Shop first or include Shop in the same request.
If your app unpublishes from Shop, unpublish from dependent channels first or include those removals in the same request.
If your app creates active products with the REST Admin API, send
"published": false, then publish to Shop and Online Store withpublishablePublish.On dated versions, Shopify can publish to Shop or remove from dependent channels even when your request didn't name them. To control the result, send Shop and its dependent channels together.
Errors
Handle these failures as validation errors. Retrying the same request returns the same error.
Publishing requests fail with
For the store setup, Shop publication is a prerequisite.Unpublishing requests fail with
For the store setup, unpublishing from dependent publications is a prerequisite.
Deprecated taxable and new productCategoryId on custom line items
On GraphQL Admin API version 2027-01 and later, DraftOrderLineItemInput.taxable and the taxable argument on orderEditAddCustomItem are marked as deprecated. Apps on 2026-10 or earlier see no schema change. Shopify recommends productCategoryId instead. It assigns a category from Shopify's Standard Product Taxonomy and lets Shopify work out the item's tax treatment.
What happens to taxable
Stores using Shopify Tax managed mode:
taxableis ignored on custom line items in every API version. The product category sets the tax treatment, and a custom line item with no category is treated as Uncategorized and taxed at the standard rate.All other stores:
taxableworks as before.taxable: falsestill means the item isn't taxed. When the item is taxed, Shopify can use its category to calculate tax.Reading
taxableis not deprecated. Fields that return whether a line item is taxable, and webhook payloads that include taxable state, are unchanged.
New: productCategoryId
You can now assign a taxonomy category to custom line items in draft orders and order edits. A category can express reduced rates, exemptions and category-specific tax rules that a yes-or-no taxable value can't.
Draft orders:
DraftOrderLineItemInput.productCategoryIdsets the category indraftOrderCreate,draftOrderUpdateanddraftOrderCalculate. It is ignored whenvariantIdis provided.Reading it back: use
DraftOrderLineItem.productCategoryandCalculatedDraftOrderLineItem.productCategory, which returnnullfor product variant line items. For order edits, useCalculatedLineItem.productCategory.Order edits:
orderEditAddCustomItemaccepts a newproductCategoryIdargument.If the ID doesn't match a category in the current taxonomy, the mutation returns a user error.
To find a category ID, use the taxonomy query, then pass the ID as productCategoryId:
query {
taxonomy {
categories(search: "t-shirts", first: 5) {
nodes {
id
fullName
}
}
}
}Checkout footer visibility clarification
The visibility fields on CheckoutBrandingFooterContent and CheckoutAndAccountsConfigurationBrandingFooterContent now control only merchant-configurable footer content. This is a clarification of behaviour, not a schema change.
Merchant-configurable footer content includes merchant policy links and copyright copy. Shopify-provided transaction information is part of checkout and isn't controlled by checkout branding. All checkout and Thank you pages can show it in the footer even when visibility is set to HIDDEN.
Who is affected
Apps that customise checkout branding for Shopify Plus stores through the legacy Checkout Branding API or the Checkout and Accounts Configuration API. This mainly matters for apps that manage footer visibility, render branding previews or run visual tests. Apps that don't manage checkout footer visibility are unaffected.
What stays the same
No fields, input types, enum values, access scopes or mutations have changed.
Existing mutations and stored branding configurations continue to work without changes.
The clarification applies to every GraphQL Admin API version where the corresponding branding type exists. It isn't tied to a new API version.
What to do and the deadline
Work through these steps for each app that writes to stores using Shopify Tax managed mode. Stores that don't use managed mode are unaffected.
Markets: in
marketCreateandmarketUpdate, either send the required defaults or omitcurrencySettingsandpriceInclusionswhen your app doesn't need to manage them. Requests that omit these inputs are unchanged. Handle failures throughuserErrors.code,userErrors.fieldanduserErrors.message.Product publishing: when publishing to Online Store, Headless, Hydrogen or Buy Button, publish to Shop first or include Shop in the same request. When unpublishing from Shop, unpublish from the dependent channels first or include those removals in the same request. Test against
unstableto see the failures, because dated versions change the request instead of failing it.REST Admin API: if your app creates active products, send
"published": false, then publish to Shop and Online Store withpublishablePublish.Custom line items: if your app sets
taxable, replace it withproductCategoryIdon GraphQL Admin API version2027-01or later. For managed-mode stores,taxableis already ignored in every version, so check any code that relies on it.Checkout branding: if your app previews or tests checkout branding, update it so Shopify-provided transaction information can remain visible when merchant-configurable footer content is hidden.
Deadline
The source announces no calendar deadline. 28 October 2026 is the date the change was announced, not a deadline. The markets validation applies across all supported API versions, and the publishing rules are rolling out gradually to managed-mode stores, so don't wait for a date to test.
The taxable deprecation affects an app when it moves to 2027-01. Apps on 2026-10 or earlier see no schema change. The versioning page lists 2027-01 as a release candidate, released on 1 January 2027, and not recommended for production. The page also says each stable version is supported for a minimum of 12 months, and lists 2026-10 as accessible until 16 October 2027, 15:00 UTC.
Get the weekly digest
One email every Monday: what changed in Shopify, the deadlines coming up and what’s been announced, plus the week’s new guides. Free, and you can unsubscribe in one click.
Sources
- Managed mode for Shopify Tax · Shopify · accessed 28 Oct 2026
- marketCreate · Shopify · accessed 28 Oct 2026
- marketUpdate · Shopify · accessed 28 Oct 2026
- MarketCurrencySettingsUpdateInput · Shopify · accessed 28 Oct 2026
- About Shopify API versioning · Shopify · accessed 28 Oct 2026
AI-assisted, reviewed by Scott. Every claim is checked against the sources above.