Add block to a card

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

Append/insert a block into a card within an edit session.

Request

Path Parameters

oseid stringrequired

Edit session ID

section_id stringrequired

Section instance ID inside the document; a global card id (header, footer, announcement, cart_drawer) also works

application/json

Body

Bodyrequired

doc_idstringrequired

Document (template file) ID

theme_idstringrequired

Theme ID (for rendering context url)

blockobjectrequired

The block object to add, e.g. {type, settings}

indexint32

0-based insert position within the parent's blocks (the section root when parent_path is empty). Pass -1 (or any value past the end) to append. Omitted = 0 = insert at the front

parent_pathint32[]

Ancestor index path from the section root to the parent block the new block is inserted into (each element a 0-based index into a blocks array); empty = insert at top-level. e.g. parent_path=[1,0] with index=-1 appends into section.blocks[1].blocks[0].blocks

template_namestring

Template name; defaults to file location without .liquid

localestring

Rendering locale; defaults to en_US

Example

json

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

Responses

200

OK

application/json

Schema

Schema

codestring

error code

messagestring

error message

data object

sectionobject

The updated section object

htmlstring

Rendered section HTML. Empty when the target is a global card (header / footer / ...) — those are not re-rendered per section

Example

json

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