新增卡片内的块

POST 
/openapi/2026-01/themes/edit-sessions/:oseid/sections/:section_id/blocks

在编辑会话中，向某张卡片追加/插入一个块。

请求

Path参数

oseid string必填

编辑会话 ID

section_id string必填

文档内的 section 实例 ID；也可传全局卡片 id（header、footer、announcement、cart_drawer）

application/json

请求体

请求体必填

doc_idstring必填

文档（模板文件）ID

theme_idstring必填

主题 ID（拼渲染上下文 url）

blockobject必填

要新增的块对象，如 {type, settings}

indexint32

在「父容器」blocks 中的 0 基插入位置（parent_path 为空时即 section 根）。传 -1（或大于末尾的值）追加到末尾。不传 = 0 = 插入到最前面

parent_pathint32[]

从 section 根到「新块要插入的父块」的祖先下标路径（每个元素是某层 blocks 数组的 0 基下标）；空 = 插入到顶层。如 parent_path=[1,0] 配合 index=-1 追加到 section.blocks[1].blocks[0].blocks 末尾

template_namestring

模板名；默认取文件 location 去掉 .liquid

localestring

渲染语言；默认 en_US

示例

json

{
  "doc_id": "string",
  "theme_id": "string",
  "block": {},
  "index": 0,
  "parent_path": [
    0
  ],
  "template_name": "string",
  "locale": "string"
}

响应

200

OK

application/json

数据结构

数据结构

codestring

错误码

messagestring

错误信息

data object

sectionobject

更新后的 section 对象

htmlstring

渲染后的 section HTML。目标为全局卡片（header / footer 等）时为空 —— 这类卡片不单独返回渲染结果

示例

json

{
  "code": "string",
  "message": "string",
  "data": {
    "section": {},
    "html": "string"
  }
}