使用Shopify productVariantUpdate mutation更新变体库存未生效问题

我尝试通过GraphQL调用Shopify的productVariantUpdate mutation来更新产品变体的库存数量，使用的mutation代码及$input参数如下：

productVariantUpdate(input: $input) {
    productVariant {
        id
        sku
        product {
            id
            title
        }
        inventoryQuantity
    }
    userErrors {
        field
        message
    }
}

$input = [
    'id' => "gid://shopify/ProductVariant/123456",
    'inventoryQuantities' => [
        "availableQuantity" => 123,
        "locationId"        => "gid://shopify/Location/123456789"
    ]
];

调用返回成功，但在Shopify后台查看时，该产品变体的库存数量并未更新，请问可能是什么原因？

• 库存设置模式不匹配
  如果该产品变体的库存由Shopify以外的系统托管（比如第三方库存同步工具、亚马逊库存管理），直接通过productVariantUpdate修改库存会被忽略。需先在Shopify后台将库存管理切换为Shopify自身托管。

• Location ID错误
  指定的locationId可能不属于当前店铺，或者该位置未给该产品变体分配库存。检查后台位置列表，确认gid://shopify/Location/123456789对应的位置存在，且该变体在该位置有库存记录。

• inventoryQuantities参数格式错误
  该参数要求是数组对象结构，你的代码中inventoryQuantities直接嵌套了键值对，缺少外层数组包裹。正确的格式应该是：

  'inventoryQuantities' => [
      [
          "availableQuantity" => 123,
          "locationId"        => "gid://shopify/Location/123456789"
      ]
  ]
  

  这是高频出错点，外层数组用于支持批量更新多个位置的库存，哪怕只更新一个位置也需要保持数组结构。

• 后台显示的是总库存而非单个位置库存
  Shopify后台产品页面默认展示所有位置的库存总和，若仅更新了单个位置的库存，其他位置的库存变化可能抵消了修改效果，或者你查看的总库存未体现单位置的更新。可进入变体的「库存」详情页，查看各位置的具体库存数值。

• 后台缓存延迟
  Shopify后台存在缓存机制，刚完成的库存更新可能需要1-5分钟才能同步显示。等待片刻后刷新页面再检查。

• API权限不足
  即便调用返回成功，若API凭证缺少write_inventory权限，实际库存更新会被静默拒绝。检查API应用的权限设置，确保包含库存写入权限。

内容的提问来源于stack exchange，提问作者codefree