メインコンテンツまでスキップ

POST /v1/items

scope​

write_items

リクエストパラメーター​

名前位置型必須説明
Idempotency-Keyヘッダーstring必須冪等キー（必須）。UUID v4 を推奨します。同一キーの再送は最初の結果をそのまま再生し、応答に Idempotent-Replay: true が付きます。同一キーで異なるボディを送ると 422 になるため、リトライは必ず同一リクエストで行ってください
kindボディenum(normalgiftticket
skuボディstring必須商品コード。ショップ内で一意にしてください。1〜32 文字
inventoryボディinteger必須初期在庫（登録時のみ）。null=無制限。set は null 固定（構成品から自動計算）
nameボディstring必須商品名。1〜64 文字
category_idボディstring必須所属カテゴリー（GET /v1/categories の id）
descriptionボディstring必須商品説明。改行を含められます。1〜2000 文字
detail_urlボディstring任意商品の詳細ページ URL。https のみ。null で消去
priceボディobject必須販売価格（税込）。割引はこの価格に対して掛かります
tax_rateボディobject必須消費税率（%）。0 / 8（軽減税率）/ 10 のいずれか
discount_rateボディinteger任意割引率（%）。割引後の金額が 50 円未満になる組み合わせは 422 price_below_minimum（割引後 = floor(price.amount × (100 − discount_rate) ÷ 100)）
discount_titleボディstring任意割引の表示名（12 文字まで）。null で消去
statusボディenum(activeinactive)任意
main_image_orientationボディenum(landscapeportraitsquare)
sell_fromボディstring任意販売開始日時。null で無期限。オフセットを付けない場合（YYYY-MM-DD HH:mm(:ss)）は日本時間（JST）として扱います。 オフセットを付けた場合（Z / +09:00）は、その指定どおりの時刻として扱います。⚠️ 応答は UTC（Z）で返るので、読んだ値をそのまま書き戻せます
sell_byボディstring任意販売終了日時。sell_from より後である必要があります。null で無期限
selling_limitsボディinteger任意1 人あたりの購入上限（個）。null で上限なし
shipping_date_estimateボディstring任意発送時期の目安。購入画面にそのまま表示される自由文
is_shippingボディboolean任意配送を伴うか。⚠️ kind=gift は false 固定（true を送ると 422 gift_must_not_ship）
shipping_costボディobject任意この商品にかかる送料。null でショップ既定の送料を使う
share_button_enabledボディboolean任意購入画面にシェアボタンを出すか
delivery_datetime_possibilityボディenum(nullablerequirednot_available)
restock_notificationボディboolean任意在庫切れ時に再入荷通知を受け付けるか
number_of_setsボディinteger任意1 口あたりの枚数。チケット系（ticket / free_ticket / pre_sale_ticket）では必須で、省略すると 422 number_of_sets_required
cancellationボディobject必須購入者によるキャンセルの可否と期限
ticketボディobject任意チケットの詳細（会場・日時など）。チケット系の kind では必須で、省略すると 422 ticket_info_required
bundleボディobject任意セット商品の構成品。kind=set では必須（1 件以上）。それ以外の kind で指定すると 422 bundle_not_allowed
variation_axesボディarray任意バリエーション軸（サイズ・色など）。作成時のみ指定できます。後からの変更・追加は 409 になります
variantsボディarray任意バリエーション SKU（variation_axes と同時指定。在庫は在庫 EP で更新）
external_refボディstring任意連携元システムでの商品 ID。指定するとその商品はこのクライアントの管理下に置かれます。以後、販売者が管理画面で手動変更した商品に対する公開状態の書き戻しは 409 で止まり、手動の変更が上書きされません

レスポンスの例​

{
  "data": {
    "id": "1",
    "sku": "string",
    "name": "string",
    "status": "active",
    "kind": "normal",
    "price": {
      "amount": 3200,
      "currency": "JPY"
    },
    "inventory": 0,
    "for_gift": true,
    "category_id": "string",
    "main_image": "string",
    "created_at": "2026-06-01T03:00:00Z",
    "updated_at": "2026-06-01T03:00:00Z",
    "sell_from": "2026-06-01T03:00:00Z",
    "sell_by": "2026-06-01T03:00:00Z",
    "external_ref": "string",
    "managed_by": "string",
    "archived": true,
    "description": "string",
    "shipping_cost": {
      "amount": 3200,
      "currency": "JPY"
    },
    "detail_url": "string",
    "main_image_orientation": "landscape",
    "restock_notification": true,
    "cancellation": {
      "enabled": true,
      "cancel_by": "string"
    },
    "ticket": {
      "event_group": "string",
      "venue_name": "string",
      "venue_address": "string",
      "doors_open_at": "2026-06-01T03:00:00Z",
      "entry_start_at": "2026-06-01T03:00:00Z",
      "valid_from": "2026-06-01T03:00:00Z",
      "valid_by": "2026-06-01T03:00:00Z",
      "term_and_condition": "string",
      "allow_continuous_use": true,
      "default_seat_label": "string",
      "background_color": "string",
      "lottery": {
        "date": "string",
        "capacity": 0
      }
    },
    "bundle": {
      "components": [
        {
          "item_id": "string",
          "quantity": 0,
          "selection_type": "fixed"
        }
      ]
    },
    "tax_rate": 10,
    "discount_rate": 0,
    "delivery_datetime_possibility": "nullable",
    "shipping_date_estimate": "ご注文から3〜5営業日で発送",
    "selling_limits": 10,
    "discount_title": "夏の大感謝祭",
    "is_shipping": true,
    "share_button_enabled": true,
    "number_of_sets": 1,
    "category_name": "スキンケア",
    "images": [
      {
        "id": "1",
        "url": "https://api.developers.atouch.jp/items/342/abc.jpg",
        "sort": 0
      }
    ],
    "variation_axes": [
      {
        "id": "string",
        "name": "色",
        "values": [
          {
            "id": "string",
            "name": "M"
          }
        ]
      }
    ],
    "variants": [
      {
        "id": "1",
        "sku": "string",
        "name": "白 / M",
        "price": {
          "amount": 3200,
          "currency": "JPY"
        },
        "inventory": 0,
        "discount_rate": 0,
        "status": "active",
        "axis_values": [
          {
            "axis": "string",
            "value": "string"
          }
        ]
      }
    ],
    "options": [
      {
        "id": "string",
        "type": "choice",
        "label": "ラッピング",
        "description": "string",
        "required": true,
        "price": {
          "amount": 3200,
          "currency": "JPY"
        },
        "choices": [
          {
            "id": "string",
            "text": "化粧箱",
            "price": {
              "amount": 3200,
              "currency": "JPY"
            }
          }
        ]
      }
    ]
  }
}

解説​

商品を新規登録します。kind（normal / gift / ticket / free_ticket / set / pre_sale_ticket）ごとの追加ルールがあり、チケット系は number_of_sets と ticket、先行販売チケットは ticket.lottery（抽選日は sell_by 以降）、セットは bundle.components（1 件以上・セットの入れ子不可・在庫は構成品から自動計算のため inventory: null 固定）が必要です。sku は店舗内で一意（重複は 409）。初期在庫は登録時のみ設定できます（以後の増減は在庫更新 API / 予約フローへ）。画像が無い商品は active にできないため inactive で登録し、画像 API で画像を設定してから公開してください（登録→画像→公開が API だけで完結します）。バリエーション商品は variation_axes（軸は 2 つまで・値は軸ごと 20 まで）と variants（組合せごとの SKU・価格・初期在庫）を同時に指定し、商品側の inventory は null にします（在庫は variant 単位）。軸は作成時にのみ指定でき、後から変更・追加はできません（変更しようとすると 409）。成功時は登録された商品の全項目を返すので再取得は不要です。Idempotency-Key 必須。

エラーレスポンスの例​

{
  "error": {
    "code": "insufficient_scope",
    "message": "requires scope 'write_items'",
    "request_id": "req_01H..."
  }
}

返しうるエラー: 400 / 401 / 403 / 409 / 422 / 500 / 503