Shopify Tax「managed mode」 米国販売の税設定を守るため、Admin API の書き込みに検証が入る

図解 ： Shopify Tax「managed mode」で変わる Admin API の書き込みルール Developer Changelog / Shopify Tax・Admin API Shopify Tax「managed mode」 米国販売の税設定を守るため、Admin API の書き込みに検証が入る managed mode を使うストアでは、マーケットの通貨・税表示、商品の公開チャネル、カスタム明細の課税方法を Shopify 側が管理する。要件と食い違う API 書き込みはバリデーションエラーになる。 このページの構成 そもそも何が変わるのか（30秒で理解） 4つの変更カテゴリを一枚で Breaking ： Markets API は US の既定値に固定 Breaking ： 商品公開は Shop チャネルが前提 Deprecated／New ： カスタム明細は taxable から productCategoryId へ Clarification ： チェックアウトのフッター表示 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が変わるのか Shopify Tax の managed mode は、米国向け販売で正しい税の扱いを適用するために、Shopify が 一部のストア設定や API の挙動を直接管理する モード。 設定の整合性を保つため、一部の Admin API の書き込みが managed mode の要件で検証されるようになった。 これまで通り動くリクエスト すでに要件どおりの設定を送っているもの、またはアプリが管理する必要のない設定を 省略している もの。 エラーになりうるリクエスト managed mode の要件を 上書きしようとする もの。バリデーションエラーが返る可能性がある。 影響を受けるのは、 マーケットを設定する／商品を公開する／カスタム明細を作る／チェックアウトのブランディングをプレビューする アプリ。 また税の扱いが「単純な true/false 設定」ではなく、 より具体的な商品データやストアデータ で決まるケースも出てくる。 2 4つの変更カテゴリを一枚で Markets API と商品公開の破壊的変更は、 managed mode を使っていないストアには影響しない （米国の顧客に販売していても同様）。 3 Breaking ： Markets API は US の既定値に固定 米国販売で managed mode を使うストアでは、 marketCreate と marketUpdate が、対象マーケットの 通貨と税表示の必須既定値を上書きしようとするリクエストを拒否 する。 検証の対象になるマーケット 対象 米国を含む マーチャント管理・非リテールのマーケット 対象外 米国を含まない マーケット 対象外 リテール マーケット 対象外 サードパーティ管理 マーケット unstable を含むすべてのサポート対象 API バージョン に適用。 検証は currencySettings または priceInclusions を送ったときだけ。省略すれば従来どおり。送った場合は、 保持されている値や省略したサブフィールドの既定値を含めた結果 で検証される。 必須既定値（オプション入力として送るならこの値） 米国のみのマーケット { "currencySettings": { "baseCurrency": "USD", "localCurrencies": false }, "priceInclusions": { "taxPricingStrategy": "ADD_TAXES_AT_CHECKOUT" } } 米国＋他国（例 ： カナダ） { "currencySettings": { "localCurrencies": true }, "priceInclusions": { "taxPricingStrategy": "INCLUDES_TAXES_IN_PRICE_BASED_ON_COUNTRY" } } エラーの見分け方 違反の種類 userErrors.code 備考 通貨 UNSUPPORTED_CURRENCY — 税表示 INCOMPATIBLE_CONFIGURATION API 2026-07 以降 税表示 GENERIC_ERROR それより前のバージョン エラーは userErrors.code ／ userErrors.field ／ userErrors.message で処理する。 4 Breaking ： 商品公開は Shop チャネルが前提 managed mode のストアでは、 Online Store／Headless／Hydrogen／Buy Button に公開する商品は、 Shop にも公開されている必要がある。これらは Shop に依存するチャネル（依存チャネル）として扱われる。 unstable と dated バージョンで挙動が違う ルール違反のリクエスト unstable dated バージョン 依存チャネルに公開 （Shop なし） 失敗 自動補正 Shop にも公開。Shop は予約公開非対応のため、依存チャネルが予約でも Shop は即時公開 Shop から公開停止 （依存チャネル残り） 失敗 自動補正 依存チャネルからも外す productCreate / productUpdate 失敗 自動補正 依存チャネルに載せると Shop を追加。 productUpdate の publications に Shop が無い場合、Shop は維持 publicationUpdate の autoPublish 失敗 自動補正 依存チャネルで ON → Shop も ON。Shop で OFF → 依存チャネルも OFF Shop が拒否／要対応フラグ 失敗 ブロックしない 補正後もルール違反 （例 ： 下書き商品を Shop なしで依存チャネルに予約） 失敗 失敗 unstable と同じエラー 失敗したリクエストは一部も保存されない。段階的にロールアウト中で、スキーマ変更はなし。REST Admin API の product／product listing／product publication も同様に振る舞う。 検証の対象 API と細かいルール 対象 API GraphQL / REST publishablePublish ・ publishableUnpublish ・ publicationUpdate 。非推奨の productPublish ・ productUnpublish 、 productCreate ／ productUpdate の公開系フィールドも対象。REST の product 作成・更新は、Shop に無い（または Shop がブロックしている）商品を Online Store に載せると失敗。 「チャネル上にある」の定義 公開・予約・下書き追加 公開済み、公開予約中、または下書き商品ならチャネルに追加済み。Shop と依存チャネルを両方含むリクエストは 順不同でまとめて 検証される。 Shop によるブロック 拒否／要対応フラグ Shop にブロックされた商品が依存チャネルに残る結果になると、Shop だけに公開するリクエストでも publishablePublish は失敗。 productUpdate も同様。 productUpdate の注意 publications は全置換 置換後のリストに依存チャネルを含むなら、既に Shop 上にあっても Shop を必ず含める 。status も変える場合は新しい status で検証される。 エラーメッセージ（再試行しても同じエラー） リクエスト メッセージ 公開 For the store setup, Shop publication is a prerequisite. 公開停止 For the store setup, unpublishing from dependent publications is a prerequisite. アプリ側の対応手順（REST で active 商品を作る場合） 1 "published": false で作成 REST Admin API で商品を作る時点では公開しない。 2 publishablePublish を呼ぶ Shop と Online Store を対象にする。 3 Shop と依存チャネルをセットで送る dated バージョンでの意図しない自動補正を避けられる。 5 Deprecated／New ： カスタム明細は taxable から productCategoryId へ ストア taxable の扱い productCategoryId の扱い managed mode あり 無視 全 API バージョンで 税の扱いを決める入力 カテゴリ未指定は Uncategorized として 標準税率 で課税 managed mode なし 従来通り taxable: false なら非課税 課税される場合、Shopify が税計算にカテゴリを使える スキーマ上の変化 非推奨化 2027-01 以降 DraftOrderLineItemInput.taxable と orderEditAddCustomItem の taxable 引数が deprecated。2026-10 以前はスキーマ変更なし。 変わらない 読み取り側 課税状態を返すフィールドや、課税状態を含む Webhook ペイロードは変更なし。 読み取りは非推奨ではない 。 新設 入力と読み取り 下書き注文 ： draftOrderCreate ／ Update ／ Calculate の productCategoryId 。注文編集 ： orderEditAddCustomItem に新引数。 実装フロー 1 taxonomy クエリで ID を検索 カテゴリ名で検索して id と fullName を得る。 2 productCategoryId に渡す 現行タクソノミーに無い ID はユーザーエラー。 variantId 指定時は無視される。 3 productCategory で読み戻す DraftOrderLineItem ／ CalculatedDraftOrderLineItem ／ CalculatedLineItem 。バリアント明細では null。 query { taxonomy { categories(search: "t-shirts", first: 5) { nodes { id fullName } } } } managed mode のストアで 下書き注文全体を免税 にしたい場合は、顧客・会社・会社ロケーションを tax-exempt にする。 1 明細だけ免税 にするならカテゴリを使う。 6 Clarification ： チェックアウトのフッター表示 CheckoutBrandingFooterContent と CheckoutAndAccountsConfigurationBrandingFooterContent の visibility は、 マーチャントが設定できるフッターコンテンツだけ を制御する。 visibility が HIDDEN でも、すべてのチェックアウトと Thank you ページは Shopify 提供の取引情報 をフッターに表示しうる。これはチェックアウトの一部で、ブランディングでは制御できない。 フィールド・入力型・enum・スコープ・mutation の変更はなし。新 API バージョンに紐づかない。既存の設定もそのまま動く。 影響 ： レガシーの Checkout Branding API または Checkout and Accounts Configuration API で Shopify Plus ストアのブランディングを扱うアプリのうち、フッター表示の管理・プレビュー描画・ビジュアルテストを行うもの。フッター表示を管理しないアプリは影響なし。 7 技術者が押さえるべき5つのポイント 1. 「管理しないなら送らない」が基本方針 Markets の currencySettings ／ priceInclusions は、省略すれば検証されない。送る場合は省略サブフィールドの既定値まで含めて検証されるので、送るなら必須既定値に合わせる。 2. 公開系は API バージョンで挙動が分かれる unstable は失敗、dated は Shopify が Shop の追加や依存チャネルの解除を 勝手に補正して保存 する。名前を出していないチャネルが変わりうるので、Shop と依存チャネルを常にセットで送る。 3. リトライしても直らない 公開系のエラーはバリデーションエラーで、同じリクエストを再試行しても同じエラーになる。リトライキューに入れず、リクエスト内容を直す分岐にする。 4. エラーコードはバージョン依存 税表示違反は 2026-07 以降 INCOMPATIBLE_CONFIGURATION 、それ以前は GENERIC_ERROR 。通貨違反は UNSUPPORTED_CURRENCY 。メッセージ文字列だけでなく code と field で判定する。 5. taxable は「読むのは OK、書くのは置き換え」 managed mode では taxable の書き込みが 全バージョンで無視 され、カテゴリ未指定のカスタム明細は標準税率で課税される。 taxable: false で非課税にしていたアプリは、managed mode のストアでは意図せず課税になりうる。2027-01 以降は productCategoryId へ移行。課税状態の読み取りと Webhook は変更なし。 8 業務に活かせる3つのユースケース USE CASE 1 商品連携アプリ／PIM 連携の公開処理を managed mode 対応に改修 課題 外部 PIM や基幹から商品を同期し、Online Store や Headless だけに公開している。managed mode のストアでは unstable で失敗、dated では Shop へ勝手に公開される。 打ち手 公開リクエストで Shop と依存チャネルを常にセットで送る。公開停止は依存チャネルを先に外すか同じリクエストに含める。REST で作る場合は "published": false → publishablePublish 。 効果 dated バージョンの自動補正による「意図しないチャネル状態」を防ぎ、将来 unstable の挙動に揃っても壊れない。 技術メモ productUpdate の publications は全置換なので、Shop 上にある商品でも Shop を毎回含める。エラーはリトライ対象外として扱う。 USE CASE 2 B2B・電話注文の下書き注文で、カスタム明細の税区分を正しく付ける 課題 見積・電話注文アプリが taxable: false でカスタム明細を非課税にしていたが、managed mode のストアでは無視され標準税率で課税される。 打ち手 taxonomy クエリでカテゴリ ID を引き、 DraftOrderLineItemInput.productCategoryId ／ orderEditAddCustomItem に渡す。注文全体の免税は顧客・会社・会社ロケーションの tax-exempt で対応。 効果 軽減税率・免税・カテゴリ別ルールを明細単位で表現でき、二択の taxable より正確な税計算になる。 技術メモ variantId 指定の明細では無視される。保存結果は productCategory で読み戻して検証。2027-01 以降は taxable 入力が deprecated。 USE CASE 3 マーケット設定ツール／越境 EC 構築の設定投入を検証付きにする 課題 マーケットの通貨・税込表示を一括投入するツールや構築テンプレートが、managed mode のストアで米国を含むマーケットに独自の値を書き込み、エラーになる。 打ち手 米国のみ ： USD／ localCurrencies: false ／ ADD_TAXES_AT_CHECKOUT 。米国＋他国 ： localCurrencies: true ／ INCLUDES_TAXES_IN_PRICE_BASED_ON_COUNTRY 。管理不要なら入力自体を省略。 効果 投入失敗を事前に避け、構築時の手戻りを減らせる。 技術メモ UNSUPPORTED_CURRENCY と INCOMPATIBLE_CONFIGURATION （2026-07 未満は GENERIC_ERROR ）を拾って、どのフィールドが要件違反かを userErrors.field で表示する。 チェックアウトのブランディングプレビューやビジュアルテストを持つアプリは、フッターを HIDDEN にしても Shopify 提供の取引情報が表示されたままになりうる 前提で、期待値（スナップショット）を更新しておく。 9 提案で使える1行サマリ 「Shopify Tax managed mode のストアでは、 米国マーケットの通貨・税表示、Shop 前提の商品公開、カテゴリ基準のカスタム明細課税 を Shopify が守る。 アプリは 管理しない設定は送らない・Shop とセットで公開する・taxable を productCategoryId に置き換える の3点で対応できる。」 source ： shopify.dev / changelog / managed-mode-for-shopify-tax-is-released 原文公開日 ： 2026-10-28（Developer Changelog）