# POST /api/items/{id}

商品編集

指定した商品の内容を変更します。

変更するフィールドだけを指定できます。
省略したフィールドは変更しません。
`null` を受け付けるフィールドは、`null` を指定すると値をクリアできます。

`price` を指定すると、適用中のセール割引が解除され、`proper_price` は `null` になります。

## 要求スコープ

- `items.read`
- `items.update`

## パラメータ

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | `string` | 必須 | 商品 ID（1 以上の整数を文字列で表したもの） |

## リクエストボディ

`application/json`

- `name` string（任意 / 1 文字以上 / 255 文字以下）: 商品名（1〜255 文字）。絵文字などの 4 バイト文字は使用できません。
- `item_tax_type` ItemTaxType（任意）: 税区分。standard=標準税率、reduced=軽減税率。
- `detail` string | null（任意 / 65535 文字以下）: 商品説明文（最大 65535 文字）。絵文字などの 4 バイト文字は使用できません。null を指定すると値をクリアします。
- `identifier` string | null（任意 / 50 文字以下 / pattern: ^[a-zA-Z0-9_-]+$）: 商品コード（最大 50 文字）。半角英数字と「_」「-」のみ指定できます。null を指定すると値をクリアします。
- `price` integer（任意 / ≥ 50 / ≤ 100000000）: 販売価格（税込、円、50〜100000000 円）。ショップの設定により上限が異なります。割引は別の sale エンドポイントで設定します。送信すると、適用中のセール割引が解除され、`proper_price` は null になります。
- `quantity_limit` integer | null（任意 / ≥ 1 / ≤ 100）: 同時購入数の上限（1〜100）。null を指定すると値をクリアします。
- `subscription` ItemSubscriptionEdit（任意）: 定期便のリピート時の価格・リピート回数・課金周期。送らなかったフィールドは変更しません。type=subscription のときのみ指定できます。
  - `repeat_price` integer（任意 / ≥ 50 / ≤ 100000000）: 継続サイクルの販売価格（税込、円、50〜100000000 円）。ショップの設定により上限が異なります。省略時は商品本体価格と同額になり、初回・継続の価格が同じになります。
  - `repeat_times` ItemSubscriptionRepeatTimes（任意）: リピート回数。repeat_3_times / repeat_6_times / repeat_12_times は指定回数で終了し、unlimited は停止されるまで継続します。
  - `cycle_plan` ItemSubscriptionCyclePlan（任意）: 課金周期。weekly=毎週、every_2_weeks=隔週、monthly=毎月、every_45_days=45日ごと、every_2_months=隔月、every_3_months=3ヶ月ごと。
- `lottery` object（任意）: 抽選販売の応募期間・当落通知予定日時。送らなかったフィールドは変更しません。type=lottery のときのみ指定できます。
  - `application_start_at` string (date-time)（任意）: 応募開始日時（ISO 8601・UTC）
  - `application_end_at` string (date-time)（任意）: 応募終了日時（ISO 8601・UTC）
  - `scheduled_announce_at` string (date-time)（任意）: 当落通知予定日時（ISO 8601・UTC）

## レスポンスボディ（200）

`application/json`

- `item_id` integer（必須 / ≥ 0）: 作成・更新された商品の ID

## リクエスト例

```sh
curl -X POST "https://apiv2.thebase.com/api/items/123" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "item_tax_type": "standard",
  "detail": "string",
  "identifier": "string",
  "price": 50,
  "quantity_limit": 1,
  "subscription": {},
  "lottery": {}
}'
```

## レスポンス

| Status | Description |
| --- | --- |
| `200` | 更新成功。更新された商品の ID を返します。 |

## エラー

エラーは `application/problem+json` の Problem 形式で返します。認証・スコープ・予期しない内部エラーなど、すべてのエンドポイントに共通のエラーと構造・判別方法は [エラーレスポンス](/docs/errors.md) を参照してください。

このエンドポイントが返すその他のエラーは次のとおりです。

| Status | Type | Description |
| --- | --- | --- |
| `400` | `/errors/request/malformed-body` | リクエストボディをこのエンドポイントが要求する形式として解釈できない場合に返します。 |
| `400` | `/errors/items/invalid-body` | リクエストボディがエンドポイントのスキーマを満たさない場合に返します。 |
| `400` | `/errors/request/invalid-params` | 1 つ以上のパスパラメータがエンドポイントのスキーマを満たさない場合に返します。 |
| `404` | `/errors/items/not-found` | 指定した商品が存在しない、または呼び出し元から参照できない場合に返します。1 リクエストで複数の商品を指定するエンドポイント（並び順の変更など）では、そのいずれかが参照できない場合に返します。 |
| `413` | `/errors/request/body-too-large` | JSON リクエストボディが 1 MiB の上限を超える場合に返します。 |
| `415` | `/errors/request/unsupported-media-type` | JSON 形式のリクエストボディを要求するエンドポイントに、対応していない Content-Type が指定された、または Content-Type が指定されていない場合に返します。 |
| `422` | `/errors/items/write-rejected` | 商品の作成・編集・削除を業務ルールにより実行できない場合に返します (型整合性違反、種別不可変、ドメイン制約違反など)。細分化された Problem type に対応しない理由のときに返します。 |
| `502` | `/errors/internal/bad-gateway` | BASE API が処理を完了するために必要な内部処理で不整合が発生した場合に返します。 |
| `504` | `/errors/internal/gateway-timeout` | BASE API が処理を完了するために必要な内部処理が制限時間内に完了しなかった場合に返します。 |