メインコンテンツまでスキップ

GET /v1/items

scope​

read_items

リクエストパラメーター​

名前位置型必須説明
limitクエリinteger任意1 回に返す件数（1〜100）。既定 20
offsetクエリinteger任意取得を開始する位置（0 始まり）。⚠️ 走査の途中でデータが更新されると取りこぼす。注文の増分取得には after_id と updated_since を使ってください
category_idクエリstring任意カテゴリーで絞り込む
qクエリstring任意keyword on item name
statusクエリenum(activeinactiveall)
skuクエリstring任意SKU 完全一致（外部連携の突合キー）
external_refクエリstring任意外部システム商品 ID の完全一致（write_items クライアントのみ）
updated_sinceクエリstring任意ISO 8601。updated_at >= この時刻（境界を含む）の商品のみ返す（増分同期用）
archivedクエリenum(excludeincludeonly)

レスポンスの例​

{
  "data": [
    {
      "id": "1",
      "sku": "string",
      "name": "string",
      "status": "active",
      "kind": "normal",
      "price": {
        "amount": 3200,
        "currency": "JPY"
      },
      "inventory": 0,
      "reserved_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
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0,
    "total": 0
  }
}

解説​

自ショップの商品を一覧取得します。q（商品名の部分一致）・category_id・sku（完全一致）・updated_since（ISO 8601・境界を含む。前回同期以降の差分取得に使います）・limit/offset で絞り込めます。write_items を持つクライアントはさらに status（active / inactive / all）・external_ref（外部システムの商品 ID・完全一致）・archived（exclude 既定 / include / only）が使え、応答に external_ref / managed_by / archived が含まれます（読み取り専用クライアントの応答は従来どおりです）。各商品の inventory は購入手続き中の仮押さえ分を差し引いた後の数で、仮押さえ中の数は reserved_inventory で返します（手元の総数は 2 つの和）。reserved_inventory のキー自体が無い応答は「取得できなかった」ことを表し、0 とは意味が異なります。

エラーレスポンスの例​

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

返しうるエラー: 400 / 401 / 403 / 429