Shopify Products

GraphQL Admin API または CSV インポート経由で Shopify 商品を作成、更新、一括インポートします。GraphQL API または CSV インポートを通じてストアにライブ商品を生成します。

前提条件

• Admin API アクセストークン (shopify-setup スキルが未設定の場合は使用)
• shopify.config.json または .dev.vars からのストア URL および API バージョン

ワークフロー

ステップ 1: 商品データを収集

ユーザーが作成または更新したいものを判断します：

• 商品基本情報: タイトル、説明 (HTML)、商品タイプ、ベンダー、タグ
• バリエーション: オプション (サイズ、色、素材)、価格、SKU、在庫数量
• 画像: アップロード用の URL またはローカルファイル
• SEO: ページタイトル、メタディスクリプション、URL ハンドル
• 整理: コレクション、商品タイプ、タグ

以下からデータを受け入れます：

• 直接会話 (ユーザーが商品を説明)
• スプレッドシート/CSV ファイル (ユーザーがファイルを提供)
• ウェブサイトスクレイピング (ユーザーが抽出用の URL を提供)

ステップ 2: 方法を選択

シナリオ	方法
1-5 商品	GraphQL ミューテーション
6-20 商品	バッチ処理による GraphQL
20+ 商品	管理者経由の CSV インポート
既存商品の更新	GraphQL ミューテーション
在庫調整	inventorySetQuantities ミューテーション

---

ステップ 3a: GraphQL 経由で作成 (推奨)

productCreate

mutation productCreate($product: ProductCreateInput!) {
  productCreate(product: $product) {
    product {
      id
      title
      handle
      status
      variants(first: 100) {
        edges {
          node { id title price sku inventoryQuantity }
        }
      }
    }
    userErrors { field message }
  }
}

変数：

{
  "product": {
    "title": "Example T-Shirt",
    "descriptionHtml": "<p>Premium cotton tee</p>",
    "vendor": "My Brand",
    "productType": "T-Shirts",
    "tags": ["summer", "cotton"],
    "status": "DRAFT",
    "options": ["Size", "Colour"],
    "variants": [
      {
        "optionValues": [
          {"optionName": "Size", "name": "S"},
          {"optionName": "Colour", "name": "Black"}
        ],
        "price": "29.95",
        "sku": "TSHIRT-S-BLK",
        "inventoryPolicy": "DENY",
        "inventoryItem": { "tracked": true }
      },
      {
        "optionValues": [
          {"optionName": "Size", "name": "M"},
          {"optionName": "Colour", "name": "Black"}
        ],
        "price": "29.95",
        "sku": "TSHIRT-M-BLK"
      },
      {
        "optionValues": [
          {"optionName": "Size", "name": "L"},
          {"optionName": "Colour", "name": "Black"}
        ],
        "price": "29.95",
        "sku": "TSHIRT-L-BLK"
      }
    ],
    "seo": {
      "title": "Example T-Shirt | My Brand",
      "description": "Premium cotton tee in multiple sizes"
    }
  }
}

curl の例：

curl -s https://{store}/admin/api/2025-01/graphql.json \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: {token}" \
  -d '{"query": "mutation productCreate($product: ProductCreateInput!) { productCreate(product: $product) { product { id title } userErrors { field message } } }", "variables": { ... }}'

複数商品のバッチ処理: レート制限に配慮しながら各商品間に短い遅延を入れて順序立てて商品を作成します (1 秒あたり 1,000 コストポイント)。

productUpdate

mutation productUpdate($input: ProductInput!) {
  productUpdate(input: $input) {
    product { id title }
    userErrors { field message }
  }
}

変数には id (必須) と更新する任意のフィールドが含まれます。

productDelete

mutation productDelete($input: ProductDeleteInput!) {
  productDelete(input: $input) {
    deletedProductId
    userErrors { field message }
  }
}

productVariantsBulkCreate

既存商品にバリエーションを追加：

mutation productVariantsBulkCreate($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
  productVariantsBulkCreate(productId: $productId, variants: $variants) {
    productVariants { id title price }
    userErrors { field message }
  }
}

productVariantsBulkUpdate

mutation productVariantsBulkUpdate($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
  productVariantsBulkUpdate(productId: $productId, variants: $variants) {
    productVariants { id title price }
    userErrors { field message }
  }
}

---

ステップ 3b: CSV 経由の一括インポート

20+ 商品の場合、CSV を生成して Shopify 管理画面からインポートします。

CSV カラムリファレンス

必須カラム:

カラム	説明	例
Handle	URL スラグ (商品ごとにユニーク)	classic-tshirt
Title	商品名 (商品ごとに最初の行)	Classic T-Shirt
Body (HTML)	HTML 形式の説明	<p>Premium cotton</p>
Vendor	ブランドまたはメーカー	My Brand
Product Category	Shopify 標準タクソノミー	Apparel & Accessories > Clothing > Shirts & Tops
Type	カスタム商品タイプ	T-Shirts
Tags	カンマ区切りタグ	summer, cotton, casual
Published	商品が表示されるかどうか	TRUE または FALSE

バリエーションカラム:

カラム	説明	例
Option1 Name	最初のオプション名	Size
Option1 Value	最初のオプション値	Medium
Option2 Name	2 番目のオプション名	Colour
Option2 Value	2 番目のオプション値	Black
Option3 Name	3 番目のオプション名	Material
Option3 Value	3 番目のオプション値	Cotton
Variant SKU	在庫管理単位	TSHIRT-M-BLK
Variant Grams	グラム単位の重量	200
Variant Inventory Qty	在庫数量	50
Variant Price	バリエーション価格	29.95
Variant Compare At Price	元の価格 (セール用)	39.95
Variant Requires Shipping	物理商品	TRUE
Variant Taxable	税金対象	TRUE

画像カラム:

カラム	説明	例
Image Src	画像 URL	https://example.com/img.jpg
Image Position	表示順序 (1 から始まる)	1
Image Alt Text	アクセシビリティ用の代替テキスト	Classic T-Shirt front view

SEO カラム:

カラム	説明	例
SEO Title	ページタイトルタグ	`Classic T-Shirt
SEO Description	メタディスクリプション	Premium cotton tee in 5 colours

マルチバリエーション行形式

最初の行に商品タイトルと詳細が含まれます。同じ商品の後続行には Handle とバリエーション固有のカラムのみが含まれます：

Handle,Title,Body (HTML),Vendor,Type,Tags,Published,Option1 Name,Option1 Value,Variant SKU,Variant Price,Variant Inventory Qty,Image Src
classic-tshirt,Classic T-Shirt,<p>Premium cotton</p>,My Brand,T-Shirts,"summer,cotton",TRUE,Size,Small,TSH-S,29.95,50,https://example.com/tshirt.jpg
classic-tshirt,,,,,,,,Medium,TSH-M,29.95,75,
classic-tshirt,,,,,,,,Large,TSH-L,29.95,60,

CSV ルール

• UTF-8 エンコーディングが必須
• 最大ファイルサイズは 50MB
• Handle は商品ごとにユニークである必要があります -- 重複したハンドルは既存商品を更新します
• バリエーション行では変更のないフィールドのバリエーションカラムを空白のままにします
• 画像は任意の行に配置できます -- Handle で関連付けられます
• Published = TRUE で商品をすぐに表示できます

インポート手順

1. 上記のカラム形式を使用して CSV を生成
2. 利用可能な場合は assets/product-csv-template.csv からテンプレートを使用
3. https://{store}.myshopify.com/admin/products/import に移動
4. CSV ファイルをアップロード
5. プレビューを確認してインポートを確認

必要に応じてブラウザオートメーションを使用してアップロードをサポートします。

---

ステップ 4: 商品画像をアップロード

画像には 2 段階のプロセス (ステージされたアップロードと添付) が必要です。

stagedUploadsCreate

mutation stagedUploadsCreate($input: [StagedUploadInput!]!) {
  stagedUploadsCreate(input: $input) {
    stagedTargets {
      url
      resourceUrl
      parameters { name value }
    }
    userErrors { field message }
  }
}

ファイルごとの入力：

{
  "filename": "product-image.jpg",
  "mimeType": "image/jpeg",
  "httpMethod": "POST",
  "resource": "IMAGE"
}

次に、ステージされた URL にアップロードして、productCreateMedia と共に添付します：

productCreateMedia

mutation productCreateMedia($productId: ID!, $media: [CreateMediaInput!]!) {
  productCreateMedia(productId: $productId, media: $media) {
    media { alt status }
    mediaUserErrors { field message }
  }
}

ショートカット: 画像がすでに公開 URL でホストされている場合、商品作成で src を直接渡します：

{
  "images": [
    { "src": "https://example.com/image.jpg", "alt": "Product front view" }
  ]
}

---

ステップ 5: コレクションに割り当て

collectionAddProducts

mutation collectionAddProducts($id: ID!, $productIds: [ID!]!) {
  collectionAddProducts(id: $id, productIds: $productIds) {
    collection { title productsCount }
    userErrors { field message }
  }
}

コレクション ID を検索するには：

{
  collections(first: 50) {
    edges {
      node { id title handle productsCount }
    }
  }
}

---

ステップ 6: 在庫を設定

inventorySetQuantities

mutation inventorySetQuantities($input: InventorySetQuantitiesInput!) {
  inventorySetQuantities(input: $input) {
    inventoryAdjustmentGroup { reason }
    userErrors { field message }
  }
}

入力：

{
  "reason": "correction",
  "name": "available",
  "quantities": [{
    "inventoryItemId": "gid://shopify/InventoryItem/123",
    "locationId": "gid://shopify/Location/456",
    "quantity": 50
  }]
}

ロケーション ID を検索するには：

{
  locations(first: 10) {
    edges {
      node { id name isActive }
    }
  }
}

---

ステップ 7: 検証

作成された商品をクエリバックして確認します：

{
  products(first: 50) {
    edges {
      node {
        id title handle status productType vendor
        variants(first: 10) {
          edges { node { id title price sku inventoryQuantity } }
        }
        images(first: 3) { edges { node { url altText } } }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

ユーザーが確認できるよう管理者 URL を提供します：https://{store}.myshopify.com/admin/products

---

重要なパターン

商品ステータス

新しい商品はデフォルトで DRAFT です。表示を可能にするには：

{ "status": "ACTIVE" }

ステータスを ACTIVE に設定する前に、常にユーザーに確認してください。

バリエーション制限

Shopify では商品ごとに最大 100 バリエーション と 3 つのオプション (例えば Size、Colour、Material) が許可されています。さらに必要な場合は、別の商品に分割します。

価格形式

価格は文字列で、数値ではありません。常にクォートしてください："price": "29.95" で、"price": 29.95 ではなく。

HTML 説明

商品説明は HTML を受け入れます。シンプルに保つ -- Shopify のエディタは基本タグを処理します：

• <p>、<strong>、<em>、<ul>、<ol>、<li>、<h2>-<h6>
• リンク用の <a href="...">
• <img> は削除されます -- 代わりに商品画像を使用します

大規模インポート向けの一括操作

API 経由で 50+ 商品の場合、Shopify の一括操作を使用します：

mutation {
  bulkOperationRunMutation(
    mutation: "mutation ($input: ProductInput!) { productCreate(input: $input) { product { id } userErrors { message } } }"
    stagedUploadPath: "tmp/bulk-products.jsonl"
  ) {
    bulkOperation { id status }
    userErrors { message }
  }
}

これは 1 行に 1 つの商品を持つ JSONL ファイルを受け入れ、非同期で処理されます。

---

アセットファイル

• assets/product-csv-template.csv -- Shopify インポートヘッダー付きの空白 CSV テンプレート