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

POST /v1/items

scope​

write_items

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

名前位置型必須説明
Idempotency-Keyヘッダーstring必須冪等キー（必須・ADR-010）。UUID v4 推奨。同一キー再送は保存レスポンスを再生
kindボディenum(normalgiftticket
skuボディstring必須
inventoryボディinteger必須初期在庫（登録時のみ）。null=無制限。set は null 固定（構成品から自動計算）
nameボディstring必須
category_idボディstring必須
descriptionボディstring必須
detail_urlボディstring任意
priceボディobject必須
tax_rateボディobject必須
discount_rateボディinteger任意
discount_titleボディstring任意
statusボディenum(activeinactive)任意
main_image_orientationボディenum(landscapesquare)任意
sell_fromボディstring任意
sell_byボディstring任意
selling_limitsボディinteger任意
shipping_date_estimateボディstring任意
is_shippingボディboolean任意
shipping_costボディobject任意
share_button_enabledボディboolean任意
delivery_datetime_possibilityボディenum(nullablerequirednot_available)
restock_notificationボディboolean任意
number_of_setsボディinteger任意
cancellationボディobject必須
ticketボディobject任意
bundleボディobject任意

レスポンスの例​

{
  "data": {
    "id": "1",
    "sku": "string",
    "name": "string",
    "status": "active",
    "kind": "normal",
    "price": {
      "amount": 3200,
      "currency": "JPY"
    },
    "inventory": 0,
    "category_id": "string",
    "main_image": "string",
    "created_at": "string",
    "updated_at": "string",
    "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": "string",
      "entry_start_at": "string",
      "valid_from": "string",
      "valid_by": "string",
      "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",
    "sell_from": "string",
    "sell_by": "string",
    "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://cdn.example/img/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 だけで完結します）。成功時は登録された商品の全項目を返すので再取得は不要です。Idempotency-Key 必須。

エラーレスポンスの例​

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

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