Create a Block - API Documentation

Overview

To create a block in your storefront, send a POST request to the blocks endpoint. This API allows you to dynamically add UI components to your store layout.

Endpoint: POST /api/blocks/

Request Parameters

Pass the fields with the block details in the request body according to your specified Content-Type. The required fields are marked with *:

Parameter	Type	Required	Description
type*	string	Yes	The type of block to create
name*	string	Yes	The name that will identify this block
properties*	object	Yes	Configuration options for the block, including template
content	object	No	Content that will be displayed in the block (only applicable for certain block types)
lang_code	string	No	Language code for the block content (default: store's default language)

Supported Block Types

The system supports the following block types:

"menu", "my_account", "our_brands", "cart_content", 
"breadcrumbs", "template", "main", "html_block", 
"smarty_block", "checkout", "products", "categories", 
"pages", "payment_methods", "shipping_methods", "currencies", 
"languages", "product_filters", "vendor_information", 
"vendor_logo", "vendor_categories", "vendor_search"

Note: Add-ons may provide additional block types such as banners, blog, rss_feed, and tags.

Understanding Block Configuration

Before creating a block, it's important to understand how blocks are structured in the system. Let's look at how to find the right properties for your block:

Finding Block Properties

The properties of a block depend on its type and template. To understand what properties are available, let's examine an example of a products scroller block:

{
  "block_id": "22",
  "type": "products",
  "properties": {
    "template": "blocks/products/products_scroller.tpl",
    "show_price": "N",
    "enable_quick_view": "N",
    "not_scroll_automatically": "Y",
    "speed": "400",
    "scroll_per_page": "Y",
    "pause_delay": "3",
    "item_quantity": "4",
    "thumbnail_width": "160",
    "hide_add_to_cart_button": "Y",
    "outside_navigation": "Y"
  },
  "company_id": "1",
  "lang_code": "en",
  "name": "Hot deals"
}

To find the available properties for a specific block type, look at the schema files in your installation:

Core block types: app/schemas/block_manager/blocks.php
Template-specific properties: app/schemas/block_manager/templates.php
Add-on block types: app/addons/<add-on_name>/block_manager/

Tip: The easiest way to understand the required properties is to create a block in the admin panel first, then use the API to get its structure as a reference.

Content Blocks

For blocks that can display content (such as html_block, categories, etc.), you'll need to provide a content object. For example, here's a categories dropdown block:

{
  "block_id": "9",
  "type": "categories",
  "properties": {
    "template": "blocks/categories/categories_dropdown_horizontal.tpl",
    "dropdown_second_level_elements": "12",
    "dropdown_third_level_elements": "6"
  },
  "company_id": "1",
  "lang_code": "en",
  "name": "Main menu",
  "content": {
    "items": {
      "filling": "full_tree_cat",
      "parent_category_id": "",
      "sort_by": "position"
    }
  }
}

Response

If the block is created successfully, you will receive HTTP/1.1 201 Created and the block ID in the response:

{
  "block_id": 42
}

If the block couldn't be created, you will receive HTTP/1.1 400 Bad Request.

Example Request: Template Block

POST /api/blocks/

{
  "type": "template",
  "name": "Example Template",
  "properties": {
    "template": "blocks/static_templates/my_account_links.tpl"
  }
}

This request creates a template block named "Example Template" that uses the "My account links" template.

Example Request: HTML Block

POST /api/blocks/

{
  "type": "html_block",
  "name": "HTML Block Example",
  "properties": {
    "template": "blocks/html_block.tpl"
  },
  "content": {
    "content": "<p>Example text</p>"
  },
  "lang_code": "en"
}

This request creates an HTML block named "HTML Block Example" that contains simple HTML content.