Modules API
Create, read, update, and delete storefront modules in layouts, the header, and the footer. Both gateway and SSO APIs use the same payloads and validation.
Authentication and endpoints
Use the API base URL shown in this country's API reference. Send an Authorization: Bearer YOUR_TOKEN header; writes use Content-Type: application/json. Gateway tokens require the themesModules permission. SSO tokens require the scope for the requested operation.
| Operation | Gateway | SSO | SSO scope |
|---|---|---|---|
| List | GET /modules | GET /ag/modules | modules |
| Read | GET /modules/{layout_module_id} | GET /ag/modules/{layout_module_id} | modules |
| Create | POST /modules | POST /ag/modules | modules |
| Update | PUT /modules/{layout_module_id} | PUT /ag/modules/{layout_module_id} | modules |
| Delete | DELETE /modules/{layout_module_id} | DELETE /ag/modules/{layout_module_id} | modules |
Every operation is scoped to the authenticated store. Do not supply store_id or company_id. There are no additional API banner permission checks. Existing gateway/SSO rate limits apply.
List and read
Optional query parameters: layout_id (integer, 0 or greater), position (content_top, content_bottom, header, footer), page (1 or greater, default 1), and limit (1–100, default 10). Omit layout_id to include all layouts; use 0 for global modules. Results sort by sort_order, then layout_module_id.
Example: GET /modules?layout_id=0&position=header&page=1&limit=10.
List responses contain success, response (module array), results, pages, page, per_page, and request_id. An empty list is successful with response=[], results=0 and pages=0. Single reads put one module in response. Both include raw settings and banners with their description rows; banner read data is not the banner write payload.
Create and update
POST and PUT require the same fields. PUT replaces the settings object; read first and send the complete intended settings. It is not a partial update. The URL selects the module on PUT; no body layout_module_id is needed.
| Field | Required | Meaning |
|---|---|---|
| layout_id | Yes | 0 for global modules, or an existing layout ID owned by this store |
| code | Yes | Module type allowed in that layout or global position |
| component | Yes | layout for a positive layout_id; header/footer matching position for layout_id=0 |
| position | Yes | content_top/content_bottom for layouts; header/footer for global modules |
| sort_order | Yes | Integer, 0 or greater |
| settings | Yes | Object containing status and module-specific fields |
| settings.status | Yes | 0 or 1 |
| settings.name | No | Display name; use this instead of the top-level name field |
| settings.title | No | Text keyed by numeric language ID |
| settings.related_ids | No | Related page IDs for layout modules |
| banners | No | Image collection for code=banners; see below |
Create a header message:
Code(json)
Language ID 1 is illustrative. Replace it with an accepted language ID. A layout text module uses code=short_content, component=layout, position=content_top (or content_bottom), and a positive layout_id belonging to the store.
Creation returns HTTP 200 with { "success": true, "response": { "id": 123 }, "request_id": "..." }. Update and delete return HTTP 200 with a message under response. Use the returned ID for subsequent reads, updates, or deletion.
Module types and settings
Header allows custom_content and announce. Footer also allows footer_widget. Layouts allow homefeaturedcategory, banners, category_slide, product_slide, embed, info_slider, brands, faq, custom_code, and short_content. product_list is allowed on the home layout (common/home) only. Layout availability is validated against the store's layout route.
All types require settings.status. Unless called optional below, the listed settings are required. Localized text uses objects keyed by numeric language IDs.
| Code | Settings |
|---|---|
| short_content / custom_content | Optional text: localized string map |
| announce | announces array; each supplied text value must contain nonempty text, maximum 300 characters after HTML cleanup; optional url must be a URL |
| footer_widget | links array; each link requires type (1, 2, 3, or 4); optional selected array, href URL, numeric id, and localized text |
| custom_code | Optional html (must pass server Twig validation); optional vars array with name and localized value |
| faq | questions array; localized question values max 255 characters, answer values max 1500 |
| brands | limit (1–32); optional slider_disabled (0 or 1) |
| info_slider | limit (1–32), source (blog/information_ids); information_ids array when source=information_ids |
| homefeaturedcategory | limit (1–100), sort (c.sort_order/c.date_added/items_order), direction (asc/desc), source (category/all), show_details_btn (0/1); categories array (max 32) when source=category |
| category_slide | limit (1–50), source (all/category/categories), sort (c.sort_order/c.date_added/items_order), direction (asc/desc); category and category_name when source=category; categories array (max 32) when source=categories; optional slider_disabled |
| product_slide | limit (1–32), source (products/category), sort (p.sort_order/p.date_added/p.viewed/input_order), direction (asc/desc); products array (max 32) when source=products; category and category_name when source=category; optional slider_disabled |
| product_list | limit (1–99999), source (products/category/all), sort (p.sort_order/p.date_added/p.viewed/items_order), direction (asc/desc), mobile_grid (1/2); products array when source=products; category and category_name when source=category |
| embed | link URL, video_attributes object, container_attributes object; container_attributes requires position (justify-content-start/justify-content-center/justify-content-end), full_width and full_height booleans; video_attributes optionally accepts numeric width/height, string src, and 0/1 allowfullscreen/autoplay |
| banners | limit (1–32), style (0/1), banner_show_title (0/1), show_details_btn (0/1), banner_content_align (left/right/center); optional integer banner_type and string transformation/transformation_mobile |
Banner writes
Send images in the top-level banners array. Each entry requires banner_image_id, image (desktop URL), and image_mob (mobile URL). Both URLs must match this country's configured CDN. Optional fields are link and title (a language-ID-to-text map).
Use banner_image_id=0 for new images. Positive IDs must already belong to the authenticated store and the module in the URL. A new module therefore uses 0 for every image. Read responses contain description rows; convert them to the title map when writing.
Supplying banners replaces the collection: existing images omitted from the array are deleted. Sending [] removes all images; omitting banners leaves the existing collection untouched. Deleting a banners module also removes its related banner images.
Country behavior
IL validates localized module text against active system language IDs. BG, RO, SRB, UAE, and USA use the store's configured language IDs. Check the language list and the store's language configuration rather than copying example IDs.
This country accepts optional settings.banner_effect_type (fade or slide) for banners.
Europe uses the same shared endpoints on each configured country API domain. The server-selected locale owns database selection; requests do not select a different country database. There is no separate Europe documentation site in this repository.
Errors and scope
- 401: missing, invalid, or expired authentication.
- 403: missing gateway permission/SSO scope, or a layout not accessible to the store.
- 404: the requested module does not exist in this store.
- 422: invalid payload or failed creation. Validation responses include message and errors; creation failures include success=false and message.
These endpoints cover module CRUD. The management UI's reset, fetch_data, order_change, and global/layout settings actions are not exposed here. Change a module's sort_order through a complete PUT payload.