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

PATCH /v1/items/{id}

scope​

write_items

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

名前位置型必須説明
idパスstring必須item_id
Idempotency-Keyヘッダーstring必須冪等キー（必須）。UUID v4 を推奨します。同一キーの再送は最初の結果をそのまま再生し、応答に Idempotent-Replay: true が付きます。同一キーで異なるボディを送ると 422 になるため、リトライは必ず同一リクエストで行ってください
kindボディobject任意⚠️ 変更できません。 送ると 409 を返します（種別は作成時に確定）
skuボディobject任意⚠️ 変更できません。 送ると 409 を返します
inventoryボディobject任意⚠️ ここでは変更できません。 在庫は PATCH /v1/items/{id}/stock で更新します。送ると 409
variation_axesボディobject任意⚠️ 変更できません。 軸は作成時に確定します。送ると 409
variantsボディobject任意⚠️ ここでは変更できません。 追加は POST /v1/items/{id}/variants、編集は PATCH /v1/items/{id}/variants/{variantId}。送ると 409
nameボディstring任意商品名。1〜64 文字
category_idボディstring任意所属カテゴリー（GET /v1/categories の id）
descriptionボディstring任意商品説明。1〜4000 文字
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任意チケットの詳細。指定した項目だけ更新されます
bundleボディobject任意
external_refボディstring任意外部システムの商品 ID。null でクリア。設定すると当該クライアントの管理下に入る
managed_byボディenum(self)任意'self'=このクライアントの管理下に置く / null=管理を解除して手動運用へ戻す
archivedボディboolean任意true=一覧の既定から除外（外部側で消えた商品）。既存の公開状態(status)は変えない

レスポンスの例​

{
  "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"
            }
          }
        ]
      }
    ]
  }
}

解説​

商品を編集します（部分更新）。送った項目だけが変わり、送らない項目は変わりません。値を消したい場合は明示的に null を送ります（例: discount_rate: null で割引解除）。kind と sku は変更できず 409、inventory は本 API では受け付けず 400（在庫更新 API へ）。未知の項目は黙って無視せず 400 を返します。画像が無い商品を active にしようとすると 422。変更差分はマーチャントの修正ログ（管理画面と同一書式）に記録され、対象商品を含むカートは既存管理画面と同様に破棄されます（価格変更後の旧価格購入の防止）。成功時は更新後の商品全項目を返すので再取得は不要です。Idempotency-Key 必須。

エラーレスポンスの例​

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

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