POST /v1/items

Scope

write_items

Request parameters

Name	In	Type	Required	Description
`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	enum(normal	gift	ticket
`sku`	body	string	required	SKU. Keep it unique within the shop. 1-32 characters.
`inventory`	body	integer	required	Initial stock, at creation time only. `null` means unlimited. For bundle items this is fixed at `null` — stock is derived from the component items.
`name`	body	string	required	Item name, 1-64 characters.
`category_id`	body	string	required	The category this item belongs to (an `id` from `GET /v1/categories`).
`description`	body	string	required	Item description. Line breaks are allowed. 1-2000 characters.
`detail_url`	body	string	optional	URL of the item's detail page. HTTPS only. Send `null` to clear it.
`price`	body	object	required	Selling price, tax included. Discounts apply to this price.
`tax_rate`	body	object	required	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	required	Whether shoppers may cancel, and by when.
`ticket`	body	object	optional	Ticket details such as venue and time. Required for the ticket kinds; omitting it returns `422` `ticket_info_required`.
`bundle`	body	object	optional	Components of a bundle. Required when `kind` is `set` (at least one). Sending it for any other kind returns `422` `bundle_not_allowed`.
`variation_axes`	body	array	optional	Variation axes such as size or colour. They can only be set at creation time; changing or adding them later returns `409`.
`variants`	body	array	optional	Variant SKUs. Specify together with `variation_axes`. Stock is updated through the stock endpoint, not here.
`external_ref`	body	string	optional	The item ID in the system you are integrating from. Setting it places the item under this client's management. From then on, writing the publication state back to an item the merchant edited by hand returns `409`, so their manual change is not overwritten.

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

Create an item. All item kinds are supported; the write is applied synchronously. Creation is not recorded in the item history. (write_items)

Error response example

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

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

Scope​

Request parameters​

Response example​

Description​

Error response example​

Scope

Request parameters

Response example

Description

Error response example