managed mode を使うストアでは、マーケットの通貨・税表示、商品の公開チャネル、カスタム明細の課税方法を Shopify 側が管理する。要件と食い違う API 書き込みはバリデーションエラーになる。
すでに要件どおりの設定を送っているもの、またはアプリが管理する必要のない設定を省略しているもの。
managed mode の要件を上書きしようとするもの。バリデーションエラーが返る可能性がある。
米国販売で managed mode を使うストアでは、marketCreate と marketUpdate が、対象マーケットの通貨と税表示の必須既定値を上書きしようとするリクエストを拒否する。
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 で処理する。
managed mode のストアでは、Online Store／Headless／Hydrogen／Buy Button に公開する商品は、Shop にも公開されている必要がある。これらは Shop に依存するチャネル（依存チャネル）として扱われる。
| ルール違反のリクエスト | 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 も同様に振る舞う。
publishablePublish・publishableUnpublish・publicationUpdate。非推奨の productPublish・productUnpublish、productCreate／productUpdate の公開系フィールドも対象。REST の product 作成・更新は、Shop に無い（または Shop がブロックしている）商品を Online Store に載せると失敗。
公開済み、公開予約中、または下書き商品ならチャネルに追加済み。Shop と依存チャネルを両方含むリクエストは順不同でまとめて検証される。
Shop にブロックされた商品が依存チャネルに残る結果になると、Shop だけに公開するリクエストでも publishablePublish は失敗。productUpdate も同様。
置換後のリストに依存チャネルを含むなら、既に 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 Admin API で商品を作る時点では公開しない。
Shop と Online Store を対象にする。
dated バージョンでの意図しない自動補正を避けられる。
| ストア | taxable の扱い | productCategoryId の扱い |
|---|---|---|
| managed mode あり | 無視 全 API バージョンで | 税の扱いを決める入力 カテゴリ未指定は Uncategorized として標準税率で課税 |
| managed mode なし | 従来通り taxable: false なら非課税 |
課税される場合、Shopify が税計算にカテゴリを使える |
DraftOrderLineItemInput.taxable と orderEditAddCustomItem の taxable 引数が deprecated。2026-10 以前はスキーマ変更なし。
課税状態を返すフィールドや、課税状態を含む Webhook ペイロードは変更なし。読み取りは非推奨ではない。
下書き注文 ： draftOrderCreate／Update／Calculate の productCategoryId。注文編集 ： orderEditAddCustomItem に新引数。
カテゴリ名で検索して id と fullName を得る。
現行タクソノミーに無い ID はユーザーエラー。variantId 指定時は無視される。
DraftOrderLineItem／CalculatedDraftOrderLineItem／CalculatedLineItem。バリアント明細では null。
query {
taxonomy {
categories(search: "t-shirts", first: 5) {
nodes {
id
fullName
}
}
}
}CheckoutBrandingFooterContent と CheckoutAndAccountsConfigurationBrandingFooterContent の visibility は、マーチャントが設定できるフッターコンテンツだけを制御する。
visibility が HIDDEN でも、すべてのチェックアウトと Thank you ページはShopify 提供の取引情報をフッターに表示しうる。これはチェックアウトの一部で、ブランディングでは制御できない。
影響 ： レガシーの Checkout Branding API または Checkout and Accounts Configuration API で Shopify Plus ストアのブランディングを扱うアプリのうち、フッター表示の管理・プレビュー描画・ビジュアルテストを行うもの。フッター表示を管理しないアプリは影響なし。
Markets の currencySettings／priceInclusions は、省略すれば検証されない。送る場合は省略サブフィールドの既定値まで含めて検証されるので、送るなら必須既定値に合わせる。
unstable は失敗、dated は Shopify が Shop の追加や依存チャネルの解除を勝手に補正して保存する。名前を出していないチャネルが変わりうるので、Shop と依存チャネルを常にセットで送る。
公開系のエラーはバリデーションエラーで、同じリクエストを再試行しても同じエラーになる。リトライキューに入れず、リクエスト内容を直す分岐にする。
税表示違反は 2026-07 以降 INCOMPATIBLE_CONFIGURATION、それ以前は GENERIC_ERROR。通貨違反は UNSUPPORTED_CURRENCY。メッセージ文字列だけでなく code と field で判定する。
managed mode では taxable の書き込みが全バージョンで無視され、カテゴリ未指定のカスタム明細は標準税率で課税される。taxable: false で非課税にしていたアプリは、managed mode のストアでは意図せず課税になりうる。2027-01 以降は productCategoryId へ移行。課税状態の読み取りと Webhook は変更なし。
"published": false → publishablePublish。productUpdate の publications は全置換なので、Shop 上にある商品でも Shop を毎回含める。エラーはリトライ対象外として扱う。taxable: false でカスタム明細を非課税にしていたが、managed mode のストアでは無視され標準税率で課税される。taxonomy クエリでカテゴリ ID を引き、DraftOrderLineItemInput.productCategoryId／orderEditAddCustomItem に渡す。注文全体の免税は顧客・会社・会社ロケーションの tax-exempt で対応。variantId 指定の明細では無視される。保存結果は productCategory で読み戻して検証。2027-01 以降は taxable 入力が deprecated。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 で表示する。