AddFixedPriceItemでバリエーション商品を構築する

前回の記事はこちら

eBay Trading API：AddFixedPriceItemでバリエーション商品(Multi-SKU)を構築する極意

はじめに

本記事は、全42回にわたる「eBay API 実践ガイド」の第6回です。

前回（#5）は、堅牢な単一商品（Single-SKU）の出品システムを構築しました。しかし、アパレル、靴、アクセサリーなどを扱う越境 EC においては、サイズや色ごとに異なる在庫と価格を持つ 「バリエーション商品（Multi-SKU）」 の出品が避けられません。

背景・なぜこれが重要か (Motivation)

「サイズ違いの商品を別々の ItemID で出品してはダメなのか？」という疑問を抱く方も多いですが、ビジネス的には絶対に避けるべきです。

別々に出品すると、eBay の出品手数料（Insertion Fee）が余分にかかるだけでなく、最も重要な 「販売履歴（Sales History）」 が分散してしまいます。バリエーションとして1つの ItemID に統合することで、「このページから累計1,000着売れている」という実績が合算され、Best Match（eBayの検索アルゴリズム）における SEO が飛躍的に向上します。

しかし、その代償としてバリエーション出品の XML ペイロードは非常に深く、ネストされた構造になります。1箇所でも整合性が崩れるとエラーが返るため、アーキテクチャの正確な理解が求められます。

基本的な使い方（ベースライン）：バリエーションXMLの全体像

バリエーション出品では、特に「全体定義（Set）」と「個別定義（Variation）」の二重構造を理解することが重要です。

<Item> <Title>Premium Cotton T-Shirt</Title> <ListingDuration>GTC</ListingDuration> <OutOfStockControl>true</OutOfStockControl> <InventoryTrackingMethod>SKU</InventoryTrackingMethod> <ItemSpecifics> <NameValueList> <Name>Brand</Name> <Value>AwesomeApparel</Value> </NameValueList> </ItemSpecifics> <Variations> <!-- バリエーション全体で使用する軸の定義 --> <VariationSpecificsSet> <NameValueList> <Name>Color</Name> <Value>Red</Value> <Value>Blue</Value> </NameValueList> <NameValueList> <Name>Size</Name> <Value>S</Value> <Value>M</Value> </NameValueList> </VariationSpecificsSet> <!-- 個別の在庫・価格・属性定義（SKU単位） --> <Variation> <SKU>TSHIRT-RED-S</SKU> <StartPrice>19.99</StartPrice> <Quantity>10</Quantity> <VariationSpecifics> <NameValueList><Name>Color</Name><Value>Red</Value></NameValueList> <NameValueList><Name>Size</Name><Value>S</Value></NameValueList> </VariationSpecifics> </Variation> <!-- 他のバリエーションも同様に続く --> </Variations> </Item> 

実務で躓く場面・深いポイント (Core)

1. InventoryTrackingMethod は絶対に「SKU」にせよ

デフォルトでは、eBay の商品は ItemID で管理されます。しかし、バリエーションを持つ場合、後から「特定のバリエーションだけ在庫を更新したい」という際、ItemID ベースだと非常に複雑な XML を組むことになります。出品時に InventoryTrackingMethod を SKU に指定しておくことで、eBay 側の管理キーが SKU に切り替わり、在庫同期が劇的に簡単になります。

2. VariationPictures の制約（画像は1軸でしか切り替えられない）

「赤いSサイズの画像」「青いMサイズの画像」のように、すべての組み合わせに画像を設定したくなりますが、eBayの仕様上それは不可能です。バリエーション画像（<Pictures> ブロック）は、必ず1つの軸（通常は Color）にしか紐付けられません。これを破ると Error 21916587 が発生します。

3. NameとValueの厳密な文字列一致

<VariationSpecificsSet> で定義した「Color」や「Red」という文字列は、その下の <Variation> ブロック、さらには <Pictures> ブロックでも、大文字小文字・スペースに至るまで完全に一致している必要があります。

主要なエラーコード早見表

堅牢な実装：バリエーションXMLの動的ビルダーと事前検証

API エラーを防ぐために、文字列の不一致や定義の欠落を事前に検知しつつ XML を構築する Python 実装例を紹介します。

import html from typing import Dict def _validate_consistency(variation_data: Dict) -> None: """
    VariationSpecificsSet と各Variationの整合性を検証する
    """ defined_aspects = {
        name: set(values) for name, values in variation_data['aspects'].items()
    }
    defined_aspect_names = set(defined_aspects.keys()) for var in variation_data['skus']:
        var_aspect_names = set(var['specifics'].keys()) # 1. SKUの値がSetに存在するか（順方向チェック） for spec_name, spec_value in var['specifics'].items(): if spec_name not in defined_aspects: raise ValueError(f"SKU '{var['sku']}' の軸 '{spec_name}' は未定義です。") if spec_value not in defined_aspects[spec_name]: raise ValueError(f"SKU '{var['sku']}' の値 '{spec_value}' が定義済リストにありません。") # 2. Setの全軸がSKUに揃っているか（逆方向チェック） # ※eBayはスパースなバリエーション（全組み合わせの一部欠落）を許容しているため、 # 全組み合わせの網羅チェックは行いません。 missing = defined_aspect_names - var_aspect_names if missing: raise ValueError(f"SKU '{var['sku']}' に軸 {missing} の指定がありません。") def build_variations_xml(variation_data: Dict) -> str: """
    辞書データから堅牢な <Variations> ブロックのXML文字列を生成する
    """ _validate_consistency(variation_data) # 1. 全体定義 (VariationSpecificsSet) の構築 set_tags = "" for spec_name, spec_values in variation_data['aspects'].items():
        val_tags = "".join([f"<Value>{html.escape(str(v))}</Value>" for v in spec_values])
        set_tags += f"""
        <NameValueList>
            <Name>{html.escape(str(spec_name))}</Name>
            {val_tags}
        </NameValueList>
        """ # 2. 個別定義 (Variation) の構築 variation_tags = "" for var in variation_data['skus']:
        spec_tags = "".join([f"<NameValueList><Name>{html.escape(str(k))}</Name><Value>{html.escape(str(v))}</Value></NameValueList>" for k, v in var['specifics'].items()])
        variation_tags += f"""
        <Variation>
            <SKU>{html.escape(var['sku'])}</SKU>
            <StartPrice>{var['price']}</StartPrice>
            <Quantity>{var['quantity']}</Quantity>
            <VariationSpecifics>{spec_tags}</VariationSpecifics>
        </Variation>
        """ return f"""
    <Variations>
        <VariationSpecificsSet>{set_tags}</VariationSpecificsSet>
        {variation_tags}
    </Variations>
    """ 

パフォーマンス・スケーリング視点 (深度)

GTC と OutOfStockControl の魔法

実務でバリエーションを扱う際、在庫が0になった SKU は通常 Listing 自体が終了してしまいます。これを防ぐために、eBay では <OutOfStockControl>true</OutOfStockControl> という強力なフラグが用意されています。

このフラグを有効にしておくと、ある SKU の Quantity を 0 にしても出品自体は終了せず、検索結果では「Out of stock」として非表示になるだけで販売履歴（SEOパワー）を維持し続けます。商品が再入荷した際に Quantity を 1 以上に戻せば、即座に販売が再開されます。大規模セラーにとって、この機能の有効化は必須の戦略です。

まとめ

本記事では、アパレル等の販売に欠かせないバリエーション商品（Multi-SKU）の出品構造を解説しました。

• ベースライン: VariationSpecificsSet と Variation の二重構造を理解する。
• 深いポイント: 軸の不一致による API エラーを、プログラム側で事前に検知する。
• スケーリング: InventoryTrackingMethod=SKU と OutOfStockControl を組み合わせ、SEO を維持しつつ在庫管理を効率化する。

次のステップ

単一商品とバリエーション商品の「出品」が完了しました。しかし、EC の実務において出品は「始まり」に過ぎません。

次回（#7）からは、新しいフェーズである 【Trading API - 在庫管理】 に突入します。まずは 「ReviseFixedPriceItemで在庫数と価格を高速に同期する」 方法について解説します！お楽しみに。

次の記事はこちら