Save page-builder block

POST 
/openapi/2026-01/themes/page-builder/blocks

Apply edit operations (ops) to a page-builder template and save the result as a new card, then place it at the target position in the edit session; when event_type is not theme, the card is only saved and not placed on the page.

Request

application/json

Body

Bodyrequired

event_typestringrequired

Event type of the card. With theme, the response also carries type and block; other event types only save the card and do not create the single-page block

origin_template_idstringrequired

Source template ID the new card derives from. The new card's own id is returned in the response

titleobject

Block title as an i18n map, e.g. {"en-US": "...", "zh-CN": "..."}

actionstringrequired

Save action: save, save_as, update

categorystring

Category, e.g. image_with_text

second_categorystring

Second category, e.g. Carousal

imagestring

Preview image filename

originstring

Base template scope: custom or global. Empty looks up custom first, then global

opsobject[]

Operations applied to the base template before saving. At least one op is required; an empty list is rejected with 400

oseidstringrequired

Edit session ID to insert the new card into

doc_idstringrequired

Document (template file) ID for the session insert

section_idstringrequired

Target section ID whose content is replaced with the new card

theme_idstringrequired

Theme ID for the render context url of the session insert

template_namestring

Template name for the session insert; defaults to file location without .liquid

localestring

Rendering locale for the session insert; defaults to en_US

Example

json

{
  "event_type": "string",
  "origin_template_id": "string",
  "title": {},
  "action": "string",
  "category": "string",
  "second_category": "string",
  "image": "string",
  "origin": "string",
  "ops": [
    {}
  ],
  "oseid": "string",
  "doc_id": "string",
  "section_id": "string",
  "theme_id": "string",
  "template_name": "string",
  "locale": "string"
}

Responses

200

OK

application/json

Schema

Schema

codestring

error code

messagestring

error message

data object

idstring

Created/updated block ID

series_idstring

Series ID

show_templatesint32

Number of show templates in the series after the save

typestring

Full block type of the saved card, e.g. shoplazza://apps/page-builder/blocks/custom-{id}/{hash}. Use it as the card's type when placing the card on a page

blockobject

Single-block payload (name/type/settings/source) for inserting as a new section

Example

json

{
  "code": "string",
  "message": "string",
  "data": {
    "id": "string",
    "series_id": "string",
    "show_templates": 0,
    "type": "string",
    "block": {}
  }
}