GET /v1/items

Scope

read_items

Request parameters

Name	In	Type	Required	Description
limit	query	integer	optional	How many entries to return (1-100). Defaults to 20.
offset	query	integer	optional	Zero-based offset to start from. ⚠️ Entries updated mid-scan can be missed. For incremental order fetching, use after_id with updated_since instead.
category_id	query	string	optional	Filter by category.
q	query	string	optional	keyword on item name
status	query	enum(active	inactive	all)
sku	query	string	optional	Exact SKU match. Useful as a join key when reconciling with an external system.
external_ref	query	string	optional	Exact match on the item ID in the connected system. Available only to clients holding write_items.
updated_since	query	string	optional	ISO 8601. Returns only items updated at or after this time (inclusive). Use it for incremental sync.
archived	query	enum(exclude	include	only)

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
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0,
    "total": 0
  }
}

Description

List items (UCP Catalog: Search & Lookup)

Error response example

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

Possible errors: 400 / 401 / 403