Skip to content
CommerceGeek home

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.

A product card linked by a rope between a Shop sign and another storefront sign, with a small calendar page.
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 taxable input on custom line items is deprecated in favour of productCategoryId.

  • 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"
  }
}
Required defaults for a US-only marketUnverified example.

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"
  }
}
Required defaults for a US-plus-another-country marketUnverified example.

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_CONFIGURATION on API version 2026-07 and later, and GENERIC_ERROR on 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, publishableUnpublish and publicationUpdate.

  • Deprecated GraphQL publishing APIs: productPublish, productUnpublish, and the publishing fields on productCreate and productUpdate. The two mutations follow the same failure conditions as publishablePublish and publishableUnpublish.

  • 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. publishablePublish fails if Shop blocks the product and the resulting state leaves it on a dependent channel, even if the request publishes only to Shop. productUpdate fails in the same case.

  • Removing a product from Shop requires removing its dependent-channel publications, in any state. This applies to publishableUnpublish and to publicationUpdate removals 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 in publishablesToAdd.

  • publicationUpdate rejects autoPublish: true on a dependent channel when Shop's publication doesn't auto-publish. It also rejects autoPublish: false on 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 productCreate and productUpdate, Shop is added when the request puts the product on a dependent channel. On productUpdate, 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 on autoPublish for 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 with publishablePublish.

  • 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: taxable is 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: taxable works as before. taxable: false still means the item isn't taxed. When the item is taxed, Shopify can use its category to calculate tax.

  • Reading taxable is 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.productCategoryId sets the category in draftOrderCreate, draftOrderUpdate and draftOrderCalculate. It is ignored when variantId is provided.

  • Reading it back: use DraftOrderLineItem.productCategory and CalculatedDraftOrderLineItem.productCategory, which return null for product variant line items. For order edits, use CalculatedLineItem.productCategory.

  • Order edits: orderEditAddCustomItem accepts a new productCategoryId argument.

  • 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
      }
    }
  }
}
Look up a category IDUnverified example.

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 marketCreate and marketUpdate, either send the required defaults or omit currencySettings and priceInclusions when your app doesn't need to manage them. Requests that omit these inputs are unchanged. Handle failures through userErrors.code, userErrors.field and userErrors.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 unstable to 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 with publishablePublish.

  • Custom line items: if your app sets taxable, replace it with productCategoryId on GraphQL Admin API version 2027-01 or later. For managed-mode stores, taxable is 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

  1. Managed mode for Shopify Tax · Shopify · accessed 28 Oct 2026
  2. marketCreate · Shopify · accessed 28 Oct 2026
  3. marketUpdate · Shopify · accessed 28 Oct 2026
  4. MarketCurrencySettingsUpdateInput · Shopify · accessed 28 Oct 2026
  5. About Shopify API versioning · Shopify · accessed 28 Oct 2026

AI-assisted, reviewed by Scott. Every claim is checked against the sources above.