変更履歴
atouch API（/v1）の公開仕様に入った変更を、新しい順に載せています。応答への項目追加などの後方互換な追加は、バージョニングと廃止ポリシーのとおり予告なく入ります。入った内容は、このページで確認できます。
- 追加新しい項目・エンドポイント
- 変更挙動の変更（後方互換）
- 修正不具合の修正
- 説明の更新挙動は同じ
2026-10-22
429 応答を全エンドポイントで宣言し、必須ヘッダーとトークン取得時の挙動を明記しました。
429（レート制限）を全エンドポイントの仕様に宣言
これまで仕様（OpenAPI）に 429 が無く、生成 SDK が未定義の応答として扱っていました。挙動は変わっていません。429 を受けたら Retry-After（秒）の後に再送してください。
413（本文が大きすぎる）を本文を受けるエンドポイントの仕様に宣言
リクエスト本文が 1 MiB を超えると 413（payload_too_large）を返します。通常の利用で達する大きさではありません。
User-Agent ヘッダーは必須です
User-Agent の無いリクエストは、API に届く前に 403（HTML の本文）で拒否されます。これまでも同じ挙動でしたが、仕様に書かれていませんでした。連携名/バージョン (+連絡先URL) のような値を付けてください。
トークン取得の認証失敗は理由を区別しません
client_id が未知・無効化済み・client_secret 不一致のいずれでも、同じ 401（invalid_client・client authentication failed）を返します。短時間に認証失敗が続くと 429（rate_limited）になり、Retry-After の後に再送できます。code_verifier は 43〜128 文字の unreserved 文字（A-Z a-z 0-9 - . _ ~）だけを受け付けます。
アクセストークンの失効（/v1/oauth/revoke）
token にアクセストークン（JWT）を渡すと、そのトークンだけを有効期限前に失効できます（token_type_hint=access_token）。この機能を提供していない環境では 400（unsupported_token_type）を返します。リフレッシュトークンの失効は従来どおりです。
2026-10-09
在庫と注文まわりの読み取り項目を追加しました。既存の項目の値と型は変わっていません。
在庫を絶対値（inventory）で更新している場合はご確認ください。 inventory は、購入手続き中の仮押さえ分を引いた後の数です。手元の総数をそのまま送ると、仮押さえ分だけ在庫が多くなります。総数に合わせるときは、読み取った総数との差を adjustment で送ってください。
商品に、仮押さえ中の在庫数を追加
購入者が決済を始めると、在庫は先に引かれます。その数を reserved_inventory で返します。手元の総数は inventory + reserved_inventory です。
| 項目 | 型 | 説明 |
|---|---|---|
+ reserved_inventory | integer | null | 購入手続き中で仮押さえされている数。inventory が null のときは null。取得できなかったときは、キーごと省略します |
+ variants[].reserved_inventory | integer | null | 種類（バリエーション）ごとの仮押さえ数。商品詳細で返します |
{ "id": "1487", "inventory": 9,+ "reserved_inventory": 1, "variants": [ { "id": "2", "inventory": 4,+ "reserved_inventory": 0 } ] }
注文の明細に、購入された種類を追加
明細の sku は、商品（親）に現在設定されている SKU です。購入された種類は variant で特定してください。
| 項目 | 型 | 説明 |
|---|---|---|
+ variant | object | null | 購入された種類。種類の無い商品は null。取得できなかったときは、キーごと省略します |
+ variant.id | string | null | 対応する現在のバリエーション ID。特定できないときは null |
+ variant.sku | string | null | 購入時点の種類の SKU |
+ variant.name | string | 購入時点の種類名 |
{ "sku": "TS-001",+ "variant": {+ "id": "2",+ "sku": "TS-001-WH-M",+ "name": "白 / M"+ } }
注文の配送に、送り状の登録日時とお届け予定日を追加
| 項目 | 型 | 説明 |
|---|---|---|
+ tracking_registered_at | date-time | null | 送り状が登録された日時（UTC）。null は未発送を意味しません |
+ tracking_delivery_date | date | null | 送り状に登録されたお届け予定日。購入者の配送希望日（delivery_date）とは別の値です |
{ "delivery_date": "2026-10-04", "tracking_number": "1234-5678-9012",+ "tracking_registered_at": "2026-10-01T03:00:00.000Z",+ "tracking_delivery_date": "2026-10-03" }
在庫・明細・配送・注文ステータスの説明を具体化
| 対象 | 変更前 | 変更後 |
|---|---|---|
inventory | 現在の在庫 | 現在の在庫。購入手続き中の仮押さえ分を差し引いた後の数 |
在庫更新の inventory | 絶対値 SET | 絶対値 SET。指定した値でそのまま上書きします。手元の総数をそのまま指定しないでください |
明細の sku | 品番 | 商品（親）に現在設定されている SKU。購入時点の値ではありません |
tracking_number | 送り状番号 | 送り状番号。複数あるときは、最初に登録されたもの |
| 注文ステータス | 各値の意味 | 各値の意味に加えて、特典交換の注文が作成時から no_shipping になる場合があることを追記 |
API で登録・訂正した送り状と、API で変えた出荷ステータスに、時刻が正しく残るようにしました。
API で登録した送り状にも、登録日時が入るように
これまで、API で登録した送り状は登録日時が記録されず、tracking_registered_at が null でした。今後は管理画面で登録したときと同じく記録されます。それより前に API で登録した送り状は null のままです。
API で出荷ステータスを変えた注文が、増分取得に出るように
これまで、API で出荷ステータスを変えても注文の更新日時が進まず、updated_since で取得すると出てきませんでした。今後は管理画面で変えたときと同じく更新日時が進みます。前回の続きから取得している場合、変更された注文が再び出てくるので、注文 ID で重複を除いてください。
送り状の訂正で、配達日が 1 日前に返っていた不具合を修正
delivery_date を省いて訂正したときの応答で、配達日が 1 日前の日付になっていました。同じ配達日を送ったときに、訂正として記録されることもありました。
在庫更新で、手元の総数をそのまま指定できるようにしました。
在庫更新に、総在庫の指定を追加
total_inventory に手元の総数（いま売れる数 ＋ 購入手続き中の仮押さえ）を指定すると、API が仮押さえ中の数を引いて在庫を保存します。inventory・adjustment とは一緒に送れません。
| 項目 | 型 | 説明 |
|---|---|---|
+ total_inventory | integer | リクエスト。総在庫（0〜99999）。在庫を管理していない商品は 422（unlimited_inventory） |
+ expected_total_inventory | integer | リクエスト。読み取ったときの総数。total_inventory と一緒にだけ送れます。今の総数と違えば、何も書かずに 409（total_inventory_changed）を返します |
+ reserved_inventory | integer | 応答。total_inventory を指定したときだけ返ります。更新処理の中で数えた、仮押さえ中の数です |
# 読み取った値: inventory 9、reserved_inventory 1（総数 10）。倉庫を数えたら 12 だった- { "adjustment": 2 }+ { "total_inventory": 12, "expected_total_inventory": 10 }
在庫更新の 409 に、エラーコードを 2 つ追加
どちらも total_inventory を指定したときだけ返ります。何も書いていません。再送のしかたが違うので、コードで見分けてください。
| 項目 | 型 | 説明 |
|---|---|---|
+ inventory_busy | 409 | 在庫の行が別の処理（購入手続きなど）に使われていました。Retry-After の後に、同じ Idempotency-Key で再送できます |
+ total_inventory_changed | 409 | 読み取った後に総数が変わりました。商品と注文を読み直して計算し直し、新しい Idempotency-Key で送ってください |
2026-09-25
503 の応答を、再試行してよいものと、再試行しても直らないものに分けました。
503 のエラーコードを 2 種類に分離
その環境で提供していない機能は、capability_not_enabled を返します。再試行しても成功しません。一時的な不調は従来どおり service_unavailable で、Retry-After ヘッダを付けるようにしました。
| 対象 | 変更前 | 変更後 |
|---|---|---|
| 提供していない機能 | service_unavailable | capability_not_enabled（Retry-After なし。再試行しない） |
| 一時的な不調 | service_unavailable | service_unavailable（Retry-After あり。その秒数だけ待って再試行） |
HTTP/1.1 503 Service Unavailable { "error": {- "code": "service_unavailable",+ "code": "capability_not_enabled", "message": "…" } }
2026-09-24
商品の作成が失敗する不具合を直しました。
2026-08-29
商品の販売期間を一覧で返すようにし、日時の入力でオフセット付きの値を受け付けるようにしました。
商品一覧に販売期間を追加
status: active は「公開中」の意味で、購入できるとは限りません。販売期間の外にある商品は購入できません。商品詳細では以前から返していた項目です。
| 項目 | 型 | 説明 |
|---|---|---|
+ sell_from | date-time | null | 販売開始日時 |
+ sell_by | date-time | null | 販売終了日時。過ぎた商品は購入できません |
{ "id": "1487", "status": "active",+ "sell_from": "2026-08-01T00:00:00.000Z",+ "sell_by": "2026-08-31T14:59:59.000Z" }
日時の入力で、オフセット付きの値も受け付け
商品の販売期間（sell_from / sell_by）など、日時の入力項目が対象です。応答で返した UTC の値を、そのまま書き戻せるようになりました。従来の形式も引き続き使えます。
| 対象 | 変更前 | 変更後 |
|---|---|---|
2026-08-25 00:00:00 | 受け付ける | 受け付ける |
2026-08-24T15:00:00.000Z | 400 | 受け付ける |
検証エラー（400）で、どの項目が不正かを返すようにしました。
検証エラー（400）に、項目ごとの内容を追加
| 項目 | 型 | 説明 |
|---|---|---|
+ error.issues[] | array | 検証エラー（400）のときだけ付きます。問題のあった項目（path）と説明（message）の一覧です。message の文言は保証しません |
{ "error": { "code": "invalid_request", "message": "…",+ "issues": [+ { "path": "limit", "message": "…" }+ ] } }
バリエーションの応答の item_id を仕様に記載
応答には以前から含まれていましたが、仕様に載っていませんでした。
2026-08-26
日時の項目の形式を、仕様に明記しました。
日時の項目に形式（format）を明記
応答の日時の項目に date-time、日付の項目に date を仕様に明記しました（一部の項目を除きます）。応答の値は変わっていません。
送り状の訂正が失敗する不具合を直しました。
送り状の訂正が 500 になる不具合を修正
送り状番号を訂正するリクエストが、常に 500 を返していました。リクエストと応答の形は変わっていません。
2026-08-25
atouch API（/v1）の提供を開始しました。