**版本：202601**

# 查询主题列表

**GET** `/openapi/2026-01/themes`

返回店铺的主题列表，可按 `published`、`ids` 过滤。

## 请求

**Query参数**

- `published` string

  按发布状态过滤主题：`0` 未发布，`1` 已发布；不传时两者都返回。传 `1` 时最多返回一个（已发布的那个）主题，分页参数不生效
- `cursor` string

  分页游标，使用上次响应中返回的游标获取下一页
- `page_size` int32

  每页返回的主题数量，范围 1-250，默认 10
- `page` int32

  页码（从 1 开始），与 cursor 互斥
- `ids` string[]

  用于筛选的主题 ID 列表，仅返回匹配指定 ID 的主题。示例：?ids=1001&ids=1002
- `contain_ext_theme` boolean

  返回结果中是否包含扩展主题

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `count` int32

    符合筛选条件的主题总数（跨所有页）
  - `themes` object[]

    主题列表

    *   Array \[

    - `id` string

      主题的唯一标识
    - `name` string

      主题名称
    - `merchant_theme_id` string

      商家主题 ID
    - `merchant_theme_name` string

      商家主题名称
    - `merchant_theme_info` string

      主题版本标识
    - `locale` string

      主题语言环境（如 en-US、zh-CN）
    - `preset` string

      主题风格
    - `type` string

      主题类型：

      *   `shoplazza`：shoplazza内部主题
      *   `developer`：第三方开发者主题
    - `desc` string

      主题的多语言描述
    - `default` string

      是否为默认主题（0 或 1）
    - `pc_cover_url` string

      PC 端封面图片 URL
    - `mobile_cover_url` string

      移动端封面图片 URL
    - `published` string

      主题是否已发布（0 或 1）
    - `is_auto_upgrade` string

      主题是否自动升级
    - `status` string

      主题的状态
    - `updated_at` string

      主题最后更新时间
    - `publish_time` string

      发布时间
    - `auto_save_time` string

      自动保存时间
    - `theme_save_time` string

      主题最后保存时间
    - `version` string

      当前主题版本
    - `c_version` string

      当前客户端版本
    - `change_log` string

      主题的更新日志信息
    - `version_publish_time` string

      版本发布时间
    - `newest_c_version` string

      最新可用客户端版本
    - `has_newest_version` boolean

      主题是否为最新版本
    - `has_draft` boolean

      是否有草稿
    - `theme_version_id` string

      主题的版本 ID
    *   \]
  - `cursor` string

    下一页游标
  - `has_more` boolean

    是否有更多记录

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "count": 0,
    "themes": [
      {
        "id": "string",
        "name": "string",
        "merchant_theme_id": "string",
        "merchant_theme_name": "string",
        "merchant_theme_info": "string",
        "locale": "string",
        "preset": "string",
        "type": "string",
        "desc": "string",
        "default": "string",
        "pc_cover_url": "string",
        "mobile_cover_url": "string",
        "published": "string",
        "is_auto_upgrade": "string",
        "status": "string",
        "updated_at": "string",
        "publish_time": "string",
        "auto_save_time": "string",
        "theme_save_time": "string",
        "version": "string",
        "c_version": "string",
        "change_log": "string",
        "version_publish_time": "string",
        "newest_c_version": "string",
        "has_newest_version": true,
        "has_draft": true,
        "theme_version_id": "string"
      }
    ],
    "cursor": "string",
    "has_more": true
  }
}
```