# POST /api/orders/{unique_key}/cancel

注文キャンセル

指定した注文をキャンセルします。

キャンセル対象の注文明細は `order_line_ids` で指定できます。
一部の明細だけを指定して部分キャンセルできるのは、代引きなど一部の決済手段に限ります。
それ以外の決済手段では、キャンセル対象の未発送明細をすべて指定する必要があります。

キャンセルに伴い、決済のキャンセル、キャンセル通知メールの送信、関連イベントの通知などを行います。

次の場合はキャンセルできません。

- 注文が存在しない、または呼び出し元のショップに属さない場合は `404` を返します。
- キャンセル済み・発送済みなど、注文や指定した明細がキャンセルできない状態の場合は `422` を返します。

キャンセル後の注文を取得できた場合は `200`、キャンセルは成功したものの注文を取得できない場合は `204` を返します。
`204` の場合は同じリクエストを再送しないでください。更新後の注文は `GET /api/orders/{unique_key}` で取得することができます。
`5xx` の場合はキャンセルの成否を確定できないため、再送せずに注文を取得して状態を確認してください。

## 要求スコープ

- `orders.cancel`
- `orders.read`

## パラメータ

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `unique_key` | path | `OrderUniqueKey` | 必須 | 注文の一意キー（16 桁の半角英数字）。小文字は大文字として扱います。 |

## リクエストボディ

`application/json`

- `order_line_ids` integer[]（必須）: キャンセルする注文明細の ID。最低 1 件指定します。注文取得レスポンスの lines[].id に対応します。明細を指定して一部だけをキャンセルできるのは代引きなど一部の決済手段に限られ、それ以外の決済手段ではキャンセル対象の未発送明細をすべて指定します。その場合、一部だけ指定するとキャンセルできません。

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

`application/json`

- `unique_key` string（必須）: 注文の一意キー。注文詳細の取得に使う識別子です。
- `status` string（必須）: 注文状態を表す文字列。値は固定された列挙ではありません。現在の仕様で返る主な値は 'ordered'（発送待ち）、'unpaid'（入金待ち）、'unshippable'（対応開始前）、'dispatched'（発送済み）、'cancelled'（キャンセル済み）、'shipping'、'arrived' です。今後の機能追加により、新しい値が返る場合があります。
- `ordered_at` string (date-time)（必須）: 注文日時（RFC 3339, 秒精度 UTC）
- `cancelled_at` string (date-time) | null（必須）: キャンセル日時（RFC 3339, 秒精度 UTC）。未キャンセルは null です。
- `modified_at` string (date-time)（必須）: 注文の最終更新日時（RFC 3339, 秒精度 UTC）
- `via` string（必須）: 注文経路。記録が無い場合は 'default' です。
- `remark` string | null（必須）: 購入者が入力した備考
- `add_comment` string | null（必須）: ショップから注文者へのメッセージ
- `shop_memo` OrderShopMemo（必須）
  - `text` string（必須）: ショップメモ本文。未入力の場合は空文字列です。
- `mail_magazine_opt_in` boolean | null（必須）: メールマガジン購読の同意。購入時に同意を取得していない注文は null です。
- `customer` OrderCustomer（必須）
  - `name` OrderCustomerName（必須）
    - `first` string（必須）: 名
    - `last` string（必須）: 姓
    - `first_kana` string | null（必須）: 名（カナ）。未登録時は null です。
    - `last_kana` string | null（必須）: 姓（カナ）。未登録時は null です。
  - `mail_address` string（必須）: 購入時に登録されたメールアドレス。未登録時は空文字です。
  - `address` OrderCustomerAddress（必須）
    - `country` string（必須）: 国名。日本国内であれば 'Japan' です。
    - `country_code` string | null（必須）: 国コード（ISO 3166-1 alpha-2）。国コードを特定できない場合は null です。
    - `zip_code` string（必須）: 郵便番号。ハイフンの有無は保存時のままです。
    - `prefecture` string（必須）: 都道府県
    - `address` string（必須）: 市区町村・番地
    - `address2` string（必須）: 建物名・部屋番号など
    - `tel` string | null（必須）: 電話番号。未登録時は null です。
- `shipping` OrderShipping（必須）
  - `name` OrderShippingName（必須）
    - `first` string | null（必須）: 名。配送先未登録時は null です。
    - `last` string | null（必須）: 姓。配送先未登録時は null です。
  - `address` OrderShippingAddress（必須）
    - `country` string | null（必須）: 国名。配送先未登録時は null です。
    - `country_code` string | null（必須）: 国コード（ISO 3166-1 alpha-2）。未登録または国コードを特定できない場合は null です。
    - `zip_code` string | null（必須）: 郵便番号。配送先未登録時は null です。
    - `prefecture` string | null（必須）: 都道府県。配送先未登録時は null です。
    - `address` string | null（必須）: 市区町村・番地。配送先未登録時は null です。
    - `address2` string | null（必須）: 建物名・部屋番号など。配送先未登録時は null です。
    - `tel` string | null（必須）: 電話番号。未登録時は null です。
- `subscription` OrderSubscription（必須）: 定期便情報。通常注文では null です。
  - `unique_key` string | null（必須）: 定期便の一意キー。未取得時は null です。
  - `repeat_number` integer | null（必須）: 何回目の配送か
  - `repeat_times` integer | null（必須）: 配送回数の総数
- `referrer` OrderReferrer（必須）: 流入元情報。記録が無い注文は null です。
  - `site_domain` string | null（必須）: 流入元ドメイン
  - `site_param` string | null（必須）: 流入元から引き継ぐ値
- `item_count` integer（必須）: 注文に含まれる商品の点数（キャンセル明細を除いた各明細の数量の合計）
- `amounts` OrderAmounts（必須）
  - `subtotal` integer（必須）: 商品合計（円）。明細 total の合計です。
  - `shipping_fee` integer（必須）: 送料（円）。無料は 0 です。
  - `cod_fee` integer（必須）: 代引手数料（円）。対象外は 0 です。
  - `total` integer（必須）: 注文合計（円）。クーポン・送料・代引手数料・金額調整を反映した値です。
  - `coupon_discount` OrderCouponDiscount（必須）
    - `amount` integer（必須）: クーポン割引額（円）。割引なしは 0 です。
    - `note` string | null（必須）: 割引メモ（クーポンコード等）
    - `allocates_balance_log` boolean（必須）: 売上残高ログの金額配分に含めるクーポン割引かどうか
  - `coin_discount` OrderCoinDiscount（必須）
    - `amount` integer（必須）: コイン割引額（円）。割引なしは 0 です。
    - `note` string | null（必須）: 割引メモ
  - `adjustment` OrderAmountAdjustment（必須）
    - `amount` integer（必須）: 金額調整（円）。調整なしは 0 です。
  - `service_charge` OrderServiceCharge（必須）
    - `collected_fee` integer（必須）: BASE 徴収手数料（円）。未徴収の注文は 0 です。
    - `fee_type` "base" | "payid_app"（必須）: 手数料種別（base / payid_app）
  - `additional_charges` OrderAdditionalCharge[]（必須）: 追加料金の内訳。無い場合は空配列です。
    - `name` string | null（必須）: 追加料金の種別名
    - `collected_fee` integer | null（必須）: 追加料金額（円）
- `lines` OrderLine[]（必須）: 注文明細。古い順（id 昇順）に並びます。
  - `id` integer（必須）: 注文明細 ID
  - `item_id` integer（必須）: 商品 ID
  - `variation_id` integer | null（必須）: 種類 ID。種類を持たない場合は null です。
  - `title` string（必須）: 商品名。注文時点の情報です。
  - `variation` string | null（必須）: 種類名。注文時点の情報です。
  - `item_identifier` string | null（必須）: 商品コード
  - `variation_identifier` string | null（必須）: 種類コード
  - `barcode` string | null（必須）: JAN / GTIN
  - `price` integer（必須）: 単価（円）
  - `amount` integer（必須）: 数量
  - `item_total` integer（必須）: 商品分小計（円）。商品単価と数量から算出した金額です。
  - `option_total` integer（必須）: オプション分小計（円）。オプション単価の合計に数量を掛けた金額です。
  - `total` integer（必須）: 明細合計（円）。item_total と option_total の合計です。
  - `tax_mode` "standard" | "reduced"（必須）: 税区分。standard=標準税率、reduced=軽減税率。実際の税率は consumption_tax_rate を参照してください。
  - `consumption_tax_rate` integer（必須）: 消費税率（%）
  - `consumption_total_tax` integer（必須）: 明細に含まれる消費税額（円）
  - `status` string（必須）: 明細の状態。部分発送・部分キャンセルに対応するため、注文全体の状態とは別に明細ごとに保持します。
  - `shipping_method` string | null（必須）: 明細ごとの配送方法名。サイズ別配送（shipping_lines）利用時は null です。
  - `shipping_fee` integer（必須）: 明細ごとの送料（円）。サイズ別配送利用時は 0 です。
  - `shipping_start_on` string (date) | null（必須）: 予約商品の発送予定開始日（YYYY-MM-DD）。予約商品以外は null です。
  - `shipping_end_on` string (date) | null（必須）: 予約商品の発送予定終了日（YYYY-MM-DD）。未設定は null です。
  - `modified_at` string (date-time)（必須）: 明細の最終更新日時（RFC 3339, 秒精度 UTC）
  - `options` OrderLineOption[]（必須）: 明細に紐づくオプション。無い場合は空配列です。
    - `option_id` integer（必須）: オプション ID
    - `option_variation_id` integer（必須）: オプション選択肢 ID
    - `name` string（必須）: オプション名
    - `type` string（必須）: オプションの入力形式を表す文字列。値は固定された列挙ではありません。現在の仕様では 'select'（選択式）または 'form'（自由入力式）を返します。今後の機能追加により、新しい値が返る場合があります。
    - `value` string | null（必須）: オプションに指定された値。現在の仕様では、type が 'select' の場合は選択肢名、'form' の場合は入力内容を返します。値がない場合は null です。
    - `price` integer（必須）: オプション単価（円）
    - `tax_mode` "standard" | "reduced"（必須）: 税区分。standard=標準税率、reduced=軽減税率
    - `consumption_tax_rate` integer（必須）: 消費税率（%）
- `shipping_lines` OrderShippingLine[]（必須）: サイズ別配送ラインの送料配分。利用しない注文は空配列です。
  - `order_line_ids` integer[]（必須）: この配送ラインに含まれる明細 ID（OrderLine.id）の配列
  - `shipping_method` string | null（必須）: 配送方法名（サイズ込み）。未設定は null です。
  - `shipping_fee` integer（必須）: この配送ラインの送料（円）
- `delivery` OrderDelivery（必須）
  - `shipping_method` string | null（必須）: 注文全体に設定された配送方法名。サイズ別配送（shipping_lines）利用時は null です。
  - `delivery_company_id` integer（必須）: 注文全体の配送業者 ID。未指定は 0 です。
  - `tracking_number` string | null（必須）: 注文全体の伝票番号
  - `delivery_date` string (date) | null（必須）: 配送希望日（YYYY-MM-DD）。未指定は null です。
  - `delivery_time_zone` string | null（必須）: 配送希望時間帯（4 桁。例: '1214' = 12 時-14 時）。未指定は null です。
  - `dispatched_at` string (date-time) | null（必須）: 最終発送日時（RFC 3339, 秒精度 UTC）。未発送は null です。
  - `dispatches` OrderDispatch[]（必須）: 部分発送の履歴。古い順に並びます。
    - `id` integer（必須）: 発送履歴 ID
    - `delivery_company_id` integer | null（必須）: 配送業者 ID。未指定は null です。
    - `tracking_number` string | null（必須）: 追跡番号。未指定は null です。
    - `comment` string | null（必須）: 発送コメント
    - `dispatched_at` string (date-time)（必須）: 発送日時（RFC 3339, 秒精度 UTC）
    - `order_line_ids` integer[]（必須）: この発送に含まれる明細 ID の配列。部分発送に対応するため、複数の明細 ID を含む場合があります。
- `payment` OrderPayment（必須）
  - `method` string | null（必須）: 注文確定時の決済手段。未確定は null です。
  - `transactions` OrderPaymentTransaction[]（必須）: 決済トランザクション履歴
    - `method` string（必須）: 決済手段（creditcard / cvs / paypal / paypay など）
    - `collected_fee` integer | null（必須）: 決済で徴収された手数料（円）。取得できない場合は null です。
    - `status` string | null（必須）: 決済ステータス。取得できない場合は null です。
    - `transaction_id` string | null（必須）: 外部決済の取引 ID。取得できない場合は null です。
    - `amount` integer | null（必須）: 取引金額（円）。取得できない場合は null です。
    - `occurred_at` string (date-time) | null（必須）: 取引発生日時（RFC 3339, 秒精度 UTC）。取得できない場合は null です。
- `membership_rewards` OrderMembershipReward[]（必須）: メンバーシップ特典。特典が無い注文では空配列です。
  - `name` string（必須）: 特典名
  - `status` string（必須）: 特典の発送状態
- `balance_logs` OrderBalanceLog[]（必須）: 売上残高ログ。売上確定・キャンセル・配送料・差額・販売パートナー精算分を含みます。
  - `text` string（必須）: ログの説明文
  - `amount` integer（必須）: 残高の増減額（円）。プラスは増加、マイナスは減少を表します。
  - `created_at` string (date-time)（必須）: ログ発生日時（RFC 3339, 秒精度 UTC）
- `order_group` OrderGroup（必須）: 販売パートナー / セレクトショップ注文の精算情報。精算情報を表示できる注文（ブランド報酬の対象注文、またはグループ内の発送が完了したセレクトショップ注文）でのみ返します。精算対象外の販売パートナー注文や通常注文では null です。
  - `order_charge` OrderGroupCharge（必須）
    - `collected_fee` integer | null（必須）: 注文グループの徴収手数料（円）
  - `payment_transaction` OrderGroupPaymentTransaction（必須）
    - `collected_fee` integer | null（必須）: 注文グループの決済手数料（円）
    - `status` string | null（必須）: 注文グループの決済ステータス
  - `brand_charge` OrderGroupBrandCharge（必須）: ブランド報酬。該当しない場合は null です。
    - `reward_fee` integer（必須）: ブランド報酬（円）

## リクエスト例

```sh
curl -X POST "https://apiv2.thebase.com/api/orders/<unique_key>/cancel" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "order_line_ids": [
    0
  ]
}'
```

## レスポンス

| Status | Description |
| --- | --- |
| `200` | キャンセル成功。更新後の注文を返します。 |
| `204` | キャンセル成功。更新後の注文を取得できないため、レスポンス本文は返しません。 |

## エラー

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

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

| Status | Type | Description |
| --- | --- | --- |
| `400` | `/errors/request/malformed-body` | リクエストボディをこのエンドポイントが要求する形式として解釈できない場合に返します。 |
| `400` | `/errors/orders/invalid-body` | リクエストボディがエンドポイントのスキーマを満たさない場合に返します。 |
| `400` | `/errors/request/invalid-params` | 1 つ以上のパスパラメータがエンドポイントのスキーマを満たさない場合に返します。 |
| `404` | `/errors/orders/not-found` | 指定した注文が存在しない、または呼び出し元から参照できない場合に返します。 |
| `413` | `/errors/request/body-too-large` | JSON リクエストボディが 1 MiB の上限を超える場合に返します。 |
| `415` | `/errors/request/unsupported-media-type` | JSON 形式のリクエストボディを要求するエンドポイントに、対応していない Content-Type が指定された、または Content-Type が指定されていない場合に返します。 |
| `422` | `/errors/orders/not-cancellable` | 注文がキャンセルできない状態、または決済手段の都合でキャンセルできない場合に返します。対象の決済手段は注文の payment.method で確認します。 |
| `422` | `/errors/orders/payment-maintenance` | 決済がメンテナンス中のため発送またはキャンセルできない場合に返します。対象の決済手段は注文の payment.method で確認します。 |
| `422` | `/errors/orders/invalid-order-lines` | 指定した注文明細が存在しない、または操作対象として不正な場合に返します。 |
| `422` | `/errors/orders/cancel-rejected` | 細分化された Problem type に対応しない理由で、注文をキャンセルできない場合に返します。 |
| `502` | `/errors/internal/bad-gateway` | BASE API が処理を完了するために必要な内部処理で不整合が発生した場合に返します。 |
| `504` | `/errors/internal/gateway-timeout` | BASE API が処理を完了するために必要な内部処理が制限時間内に完了しなかった場合に返します。 |