PATCH /v1/items/{id}

Scope

write_items

Request parameters

Name	In	Type	Required	Description
`id`	path	string	required	item_id
`Idempotency-Key`	header	string	required	Idempotency key (required). A UUID v4 is recommended. Resending the same key replays the original result, and the response carries `Idempotent-Replay: true`. Sending a different body with the same key returns `422`, so always retry with the identical request.
`kind`	body	object	optional	⚠️ Not editable. The kind is fixed at creation; sending it returns `409`.
`sku`	body	object	optional	⚠️ Not editable. Sending it returns `409`.
`inventory`	body	object	optional	⚠️ Not editable here. Update stock through `PATCH /v1/items/{id}/stock`. Sending it returns `409`.
`variation_axes`	body	object	optional	⚠️ Not editable. Variation axes are fixed at creation. Sending it returns `409`.
`variants`	body	object	optional	⚠️ Not editable here. Add variants with `POST /v1/items/{id}/variants` and edit them with `PATCH /v1/items/{id}/variants/{variantId}`. Sending it returns `409`.
`name`	body	string	optional	Item name, 1-64 characters.
`category_id`	body	string	optional	The category this item belongs to (an `id` from `GET /v1/categories`).
`description`	body	string	optional	Item description, 1-4000 characters.
`detail_url`	body	string	optional	URL of the item's detail page. HTTPS only. Send `null` to clear it.
`price`	body	object	optional	Selling price, tax included. Discounts apply to this price.
`tax_rate`	body	object	optional	Consumption tax rate in percent: `0`, `8` (reduced rate) or `10`.
`discount_rate`	body	integer	optional	Discount rate in percent. A combination that brings the price below 50 JPY after the discount returns `422` `price_below_minimum` (discounted = floor(price.amount x (100 - discount_rate) / 100)).
`discount_title`	body	string	optional	Label shown for the discount, up to 12 characters. Send `null` to clear it.
`status`	body	enum(active	inactive)	optional
`main_image_orientation`	body	enum(landscape	portrait	square)
`sell_from`	body	string	optional	Start of the selling period. `null` means no start limit. Without an offset (`YYYY-MM-DD HH:mm(:ss)`) the value is read as Japan Standard Time (JST). With an offset (`Z` / `+09:00`) it is read as exactly the instant you specify. ⚠️ Responses return UTC (`Z`), so a value you read back can be sent as-is.
`sell_by`	body	string	optional	When the item stops being sold. Must be later than `sell_from`. `null` means no end.
`selling_limits`	body	integer	optional	Maximum quantity one shopper may buy. `null` means no limit.
`shipping_date_estimate`	body	string	optional	Free text about when the item ships, shown to shoppers as-is.
`is_shipping`	body	boolean	optional	Whether the item is shipped. ⚠️ Always `false` for `kind=gift`; sending `true` returns `422` `gift_must_not_ship`.
`shipping_cost`	body	object	optional	Shipping cost charged for this item. `null` uses the shop's default shipping cost.
`share_button_enabled`	body	boolean	optional	Whether to show a share button on the purchase screen.
`delivery_datetime_possibility`	body	enum(nullable	required	not_available)
`restock_notification`	body	boolean	optional	Whether shoppers can request a restock notification when the item is out of stock.
`number_of_sets`	body	integer	optional	Number of tickets per unit. Required for the ticket kinds (`ticket`, `free_ticket`, `pre_sale_ticket`); omitting it returns `422` `number_of_sets_required`.
`cancellation`	body	object	optional	Whether shoppers may cancel, and by when.
`ticket`	body	object	optional	Ticket details. Only the fields you send are updated.
`bundle`	body	object	optional
`external_ref`	body	string	optional	The item ID in the connected system. Send `null` to clear it. Setting it places the item under this client's management.
`managed_by`	body	enum(self)	optional	`self` = place the item under this client's management. `null` = release management and return it to manual operation.
`archived`	body	boolean	optional	`true` excludes the item from list results by default — use it for items that disappeared on the connected system. The item's own `status` is left unchanged.

Response example

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

Description

Edit an item (partial update). Depending on what changed, the item is dropped from shoppers' carts. (write_items)

Error response example

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

Possible errors: 400 / 401 / 403 / 404 / 409 / 422 / 500 / 503

Scope​

Request parameters​

Response example​

Description​

Error response example​

Scope

Request parameters

Response example

Description

Error response example