Section themes REST API

MasterPage

Master pages are configurations of page sections and content sections that apply to multiple pages of the same type.

MasterPage rules

  • Shops have one master page per page type.
  • When the default property is true, newly-created pages are automatically assigned that master page's ID as their master_page_id.
  • The default property is false by default, unless the shop was created with a section theme following the public launch of section themes. This enables shops that were created before the launch of master pages to test-drive the feature on specific pages before adopting it more widely.
  • The sections property must include the corresponding page section file for the page type (for example, pages/product.liquid for the product master page). The ID of page sections must always be page.

List of master page types:

  • product
  • collection
  • article
  • page

MasterPage properties

"shop_id": 1 The ID of the shop to which the master page belongs. Read-only.
"type": "product" One of the supported master page types. Read-only.
"name": "Product master page" A human-friendly name for the master page.
"default": true Whether the master page should be automatically assigned to new pages.
"sections": [<SectionData>] SectionData detailed here.
"version": "a4f9d3c7" A string representing the state of the master page. Read-only.
"created_at" The date and time (ISO 8601 format) when the page was created. Read-only.
"updated_at" The date and time (ISO 8601 format) when the page was last updated. Read-only.

MasterPage endpoints

GET /master_pages.json

Retrieves a list of master pages.

Parameters:

  • limit
  • last_id
  • last_value
  • order
  • direction
  • created_at_min
  • created_at_max
  • updated_at_min
  • updated_at_max
  • fields

GET /master_pages/#{id}.json

Retrieves a single master page by its ID.

Parameters:

  • fields

PUT /master_pages/#{id}.json

{
  "master_page": { … }
}

Updates a master page page.

SystemPage

System pages are the built-in pages of an online store, such as the search and cart pages.

SystemPage rules

  • System pages are created automatically on shop creation and can't be created or deleted through the API.
  • The sections property is null by default, unless the shop was created with a section theme following the public launch of section themes. This enables shops that were created before the launch of section themes to adopt the sections feature on a per-page basis.
  • When the sections property is not null, the sections are rendered instead of the theme template.
  • When the sections property is not null, it must include the corresponding page section file for the page type (for example, pages/cart.liquid for the cart system page). The ID of page sections must always be page.
  • When the sections property is null, or when it is not null but the main theme does not include the corresponding page section file for the page type, the page is rendered with the theme template file (for example, templates/cart.liquid for the cart system page).
  • The theme_frame_id property is null by default.
  • When the theme_frame_id property is not null and the corresponding theme frame exists in the main theme's config/frames.json file, the page is rendered through the theme frame.
  • When the theme_frame_id property is null and the main theme includes a config/frames.json file, the page is rendered through the theme frame whose ID is equal to the page type, otherwise whose ID is default.

List of system page types:

  • 404
  • cart
  • customers/account
  • customers/activate_account
  • customers/addresses
  • customers/login
  • customers/order
  • customers/register
  • customers/reset_password
  • index
  • list-collections
  • gift_card
  • password
  • search

SystemPage properties

"id": 1 The unique numeric identifier for the system page. Read-only.
"shop_id": 1 The ID of the shop to which the system page belongs. Read-only.
"type": "cart" One of the supported system page types. Read-only.
"sections": [<SectionData>] SectionData detailed here.
"theme_frame_id": "default" A unique identifier for the theme frame (as defined in the config/frames.json file of the main theme) that the system page should be rendered through.
"created_at" The date and time (ISO 8601 format) when the page was created. Read-only.
"updated_at" The date and time (ISO 8601 format) when the page was last updated. Read-only.

SystemPage endpoints

GET /system_pages.json

Retrieves a list of system pages.

Parameters:

  • limit
  • last_id
  • last_value
  • order
  • direction
  • created_at_min
  • created_at_max
  • updated_at_min
  • updated_at_max
  • fields

GET /system_pages/#{id}.json

Retrieves a single system page by its ID.

Parameters:

  • fields

PUT /system_pages/#{id}.json

{
  "system_page": { … }
}

Updates a system page.

ProductPage

Every product has a corresponding product page in the online store channel.

ProductPage rules

  • A product page is automatically created for every product.
  • The master_page_id property is null by default, unless the product master page's default property was true when the product page was created. This enables shops that were created before the launch of section themes to adopt the sections feature on a per-page basis.
  • When the master_page_id property is not null, the sections of the master page, with the overrides of the product page applied, are rendered instead of the theme template.
  • When the master_page_id property is null, or when it is not null but the main theme does not include a pages/product.liquid page section file, the page is rendered with the templates/product.liquid theme template file, or with templates/product.#{template_suffix}.liquid if using an alternate template.
  • The theme_frame_id property is null by default.
  • When the theme_frame_id property is not null and the corresponding theme frame exists in the main theme's config/frames.json file, the page is rendered through the theme frame.
  • When the theme_frame_id property is null and the main theme includes a config/frames.json file, the page is rendered through the theme frame whose ID is product, otherwise whose ID is default.

ProductPage properties

"id": 1 The unique numeric identifier for the product page. Read-only.
"shop_id": 1 The ID of the shop to which the product page belongs. Read-only.
"product_id": 1 The ID of the product to which the product page belongs. Read-only.
"sections": [<SectionData>] SectionData detailed here. Read-only.
"overrides": [<OverrideData>] OverrideData detailed here.
"master_page_id": 1 A unique identifier for the master page that the product page should be rendered with.
"master_page_version": "a4f9d3c7" A string representing the state of the master page at the time of the request. Read-only.
"theme_frame_id": "default" A unique identifier for the theme frame (as defined in the config/frames.json file of the main theme) that the product page should be rendered with.
"created_at" The date and time (ISO 8601 format) when the page was created. Read-only.
"updated_at" The date and time (ISO 8601 format) when the page was last updated. Read-only.

ProductPage endpoints

GET /product_pages.json

Retrieves a list of product pages.

Parameters:

  • limit
  • last_id
  • last_value
  • order
  • direction
  • product_id
  • created_at_min
  • created_at_max
  • updated_at_min
  • updated_at_max
  • fields

GET /product_pages/#{id}.json

Retrieves a single product page by its ID.

Parameters:

  • fields

PUT /product_pages/#{id}.json

{
  "product_page": { … }
}

Updates a product page.

PATCH /product_pages/#{id}/overrides.json

{
  "overrides": [<OverrideData>],
  "master_page_version": "a4f9d3c7"
}

Appends an override to the product page. Overrides that cancel each other are automatically deleted.

Requires that the current version of the product page's master page be submitted along with the overrides. If the version doesn't match or the product page doesn't have a master page, an error response is returned. The format of overrides is described below.

CollectionPage

Every collection has a corresponding collection page in the online store channel.

CollectionPage rules

  • A collection page is automatically created for every collection.
  • The master_page_id property is null by default, unless the collection master page's default property was true when the collection page was created. This enables shops that were created before the launch of section themes to adopt the sections feature on a per-page basis.
  • When the master_page_id property is not null, the sections of the master page, with the overrides of the collection page applied, are rendered instead of the theme template.
  • When the master_page_id property is null, or when it is not null but the main theme does not include a pages/collection.liquid page section file, the page is rendered with the templates/collection.liquid theme template file, or with templates/collection.#{template_suffix}.liquid if using an alternate template.
  • The theme_frame_id property is null by default.
  • When the theme_frame_id property is not null and the corresponding theme frame exists in the main theme's config/frames.json file, the page is rendered through the theme frame.
  • When the theme_frame_id property is null and the main theme includes a config/frames.json file, the page is rendered through the theme frame whose ID is collection, otherwise whose ID is default.

CollectionPage properties

"id": 1 The unique numeric identifier for the collection page. Read-only.
"shop_id": 1 The ID of the shop to which the collection page belongs. Read-only.
"collection_id": 1 The ID of the collection to which the collection page belongs. Read-only.
"sections": [<SectionData>] SectionData detailed here. Read-only
"overrides": [<OverrideData>] OverrideData detailed here.
"master_page_id": 1 A unique identifier for the master page that the collection page should be rendered with.
"master_page_version": "a4f9d3c7" A string representing the state of the master page at the time of the request. Read-only.
"theme_frame_id": "default" A unique identifier for the theme frame (as defined in the config/frames.json file of the main theme) that the collection page should be rendered with.
"created_at" The date and time (ISO 8601 format) when the page was created. Read-only.
"updated_at" The date and time (ISO 8601 format) when the page was last updated. Read-only.

CollectionPage endpoints

GET /collection_pages.json

Retrieves a list of collection pages.

Parameters:

  • limit
  • last_id
  • last_value
  • order
  • direction
  • collection_id
  • created_at_min
  • created_at_max
  • updated_at_min
  • updated_at_max
  • fields

GET /collection_pages/#{id}.json

Retrieves a single collection page by its ID.

Parameters:

  • fields

PUT /collection_pages/#{id}.json

{
  "collection_page": { … }
}

Updates a collection page.

PATCH /collection_pages/#{id}/overrides.json

{
  "overrides": [<OverrideData>],
  "master_page_version": "a4f9d3c7"
}

Appends an override to the collection page. Overrides that cancel each other are automatically deleted.

Requires that the current version of the collection page's master page be submitted along with the overrides. If the version doesn't match or the collection page doesn't have a master page, an error response is returned. The format of overrides is described below.

Blog

Blog rules

  • The sections property is null by default, unless the shop was created with a section theme following the public launch of section themes. This enables shops that were created before the launch of section themes to adopt the sections feature on a per-page basis.
  • When the sections property is not null, the sections are rendered instead of the theme template.
  • When the sections property is not null, it must include the pages/blog.liquid page section file. The ID of page sections must always be page.
  • When the sections property is null, or when it is not null but the main theme does not include a pages/blog.liquid page section file, the page is rendered with the templates/blog.liquid theme template file, or with templates/blog.#{template_suffix}.liquid if using an alternate template.
  • The theme_frame_id property is null by default.
  • When the theme_frame_id property is not null and the corresponding theme frame exists in the main theme's config/frames.json file, the page is rendered through the theme frame.
  • When the theme_frame_id property is null and the main theme includes a config/frames.json file, the page is rendered through the theme frame whose ID is blog, otherwise whose ID is default.

New Blog properties

"sections": [<SectionData>] SectionData detailed here.
"theme_frame_id": "default" A unique identifier for the theme frame (as defined in the config/frames.json file of the main theme) that the blog page should be rendered with.

Article

Article rules

  • The master_page_id property is null by default, unless the article master page's default property was true when the article was created. This enables shops that were created before the launch of section themes to adopt the sections feature on a per-page basis.
  • When the master_page_id property is not null, the sections of the master page, with the overrides of the article applied, are rendered instead of the theme template.
  • When the master_page_id property is null, or when it is not null but the main theme does not include a pages/article.liquid page section file, the page is rendered with the templates/article.liquid theme template file, or with templates/article.#{template_suffix}.liquid if using an alternate template.
  • The theme_frame_id property is null by default.
  • When the theme_frame_id property is not null and the corresponding theme frame exists in the main theme's config/frames.json file, the page is rendered through the theme frame.
  • When the theme_frame_id property is null and the main theme includes a config/frames.json file, the page is rendered through the theme frame whose ID is article, otherwise whose ID is default.

New Article properties

"sections": [<SectionData>] SectionData detailed here. Read-only.
"overrides": [<OverrideData>] OverrideData detailed here.
"master_page_id": 1 A unique identifier for the master page that the article page should be rendered with.
"master_page_version": "a4f9d3c7" A string representing the state of the master page at the time of the request. Read-only.
"theme_frame_id": "default" A unique identifier for the theme frame (as defined in the config/frames.json file of the main theme) that the article page should be rendered with.

New Article endpoint

PATCH /articles/#{id}/overrides.json

{
  "overrides": [<OverrideData>],
  "master_page_version": "a4f9d3c7"
}

Appends an override to the article. Overrides that cancel each other are automatically deleted.

Requires that the current version of the article's master page be submitted along with the overrides. If the version doesn't match or the article doesn't have a master page, an error response is returned.

Page

Page rules

  • The master_page_id property is null by default, unless the article master page's default property was true when the page was created. This enables shops that were created before the launch of section themes to adopt the sections feature on a per-page basis.
  • When the master_page_id property is not null, the sections of the master page, with the overrides of the page applied, are rendered instead of the theme template.
  • When the master_page_id property is null, or when it is not null but the main theme does not include a pages/page.liquid page section file, the page is rendered with the templates/page.liquid theme template file, or with templates/page.#{template_suffix}.liquid if using an alternate template.
  • The theme_frame_id property is null by default.
  • When the theme_frame_id property is not null and the corresponding theme frame exists in the main theme's config/frames.json file, the page is rendered through the theme frame.
  • When the theme_frame_id property is null and the main theme includes a config/frames.json file, the page is rendered through the theme frame whose ID is page, otherwise whose ID is default.

New Page properties

"sections": [<SectionData>] SectionData detailed here. Read-only.
"overrides": [<OverrideData>] OverrideData detailed here.
"master_page_id": 1 A unique identifier for the master page that the page should be rendered with.
"master_page_version": "a4f9d3c7" A string representing the state of the master page at the time of the request.
"theme_frame_id": "default" A unique identifier for the theme frame (as defined in the config/frames.json file of the main theme) that the page should be rendered with.

New Page endpoint

PATCH /pages/#{id}/overrides.json

{
  "overrides": [<OverrideData>],
  "master_page_version": "a4f9d3c7"
}

Appends an override to the page. Overrides that cancel each other are automatically deleted.

Requires that the current version of the page's master page be submitted along with the overrides. If the version doesn't match or the page doesn't have a master page, an error response is returned.

The sections property

The sections property returns the data of all the sections as it would be when rendering the page, excluding the theme frame sections. For pages that support master pages, this means that the sections property gives a representation of the sections of its master page with the overrides of the page applied on top. On page resources that have an overrides property, the sections property is read-only.

<SectionData>

  • When the sections property is not empty, it must contain a page section, whose ID must be page. A page can't have more than one page section.
  • For pages of a type that supports master pages, the sections property is an empty array when master_page_id hasn't been set.
{
  "id": "content-1" The unique identifier for the section. On page section this must be "page".
  "title": "Section" A human-friendly name for the section.
  "disabled": false A boolean value. Not supported by page sections.
  "section_file": "content/grid.liquid" Indicates the path of the section file in the published theme used to render the section on the storefront. This changes when the theme is updated or a new theme is published, and may be null when the section can't be rendered. On create or update, the section file must exist.
  "content": <ContentData> An object with two keys, static and blocks, containing static and block content data objects. Only supported on content sections.
  "blocks": [<Blockdata>] An ordered array of block data objects. Only supported on page sections.
  "settings": <Settingsdata> A settings data object.
}

<ContentData>

{
  "static": [<StaticContentData>] An array of static content data objects.
  "blocks": [<BlockContentData>] An ordered array of block content data objects.
}

<StaticContentData>

{
  "id": "content-1" The unique identifier for the content.
  "type": "product" One of the content types supported by the content schema.
  "value": <ContentDataValue> The value for the built-in setting of the content.
  "settings": <SettingsData> A settings data object.
}

<BlockContentData>

{
  "id": "content-1" The unique identifier for the content.
  "type": "product" One of the content types supported by the content schema.
  "value": <ContentDataValue> The value for the built-in setting of the content.
  "settings": <SettingsData> A settings data object.
}

<ContentDataValue>

Content type Value type
richtext HTML string
image Shopify URL
external_video URL
product Product ID
collection Collection ID
blog Blog ID
article Article ID
menu Menu ID
html HTML string
custom n/a

<BlockData>

{
  "id": "block-1" The unique identifier for the block.
  "type": "product" The type of the block, as defined in the schema of the section file.
  "settings": <SettingsData> A settings data object.
}

<SettingsData>

{
  "autoplay": { The unique identifier of the setting, as defined in the schema of the section file.
    "type": "checkbox" One of the supported theme settings type.
    "value": true The value of the setting, which must be a valid value for the setting type.
  }
}

The overrides property

The overrides property is a list of section changes that have been applied to a specific page, making it differ from its master page. When a page supporting master pages and overrides is rendered, the overrides of the page are applied on top of its master page's sections to produce the final list of sections and their configuration, to be rendered on the online store.

The list of overrides can't be updated directly through the API. Instead, new overrides can be appended onto a page, which can supercede existing overrides. When appending overrides, the list is compacted to a minimal size, such that redundant overrides are deleted or combined.

In order to append an override, the current state of the master page must be submitted via the master_page_version parameter. This is to avoid accidental overrides of master page sections that may have been updated or deleted in-between the time the master page's sections were fetched and the time they are overridden.

There are nine types of overrides:

  • insert_section
  • delete_section
  • update_section
  • insert_content
  • delete_content
  • update_content
  • insert_block
  • delete_block
  • update_block

insert_section

{
  "type": "insert_section"
  "after": <SectionId> The unique identifier of the section preceding the section being inserted. null if the section is to be inserted in the first position.
  "section": <SectionData> A section data object.
}

delete_section

{
  "type": "delete_section"
  "section_id": <SectionId> The unique identifier of the section to be deleted. Only sections that have been added as an override can be deleted.
}

update_section

{
  "type": "update_section"
  "section_id": <SectionId> The unique identifier of the section to be updated.
  "disabled": <Boolean> Whether the section should be disabled. Not supported on page sections.
  "settings": <SettingsData> A settings data object.
}

insert_content

{
  "type": "insert_content"
  "section_id": <SectionId> The unique identifier of the section where the content is to be inserted.
  "after": <ContentId> The unique identifier of the content preceding the content being inserted. null if the content is to be inserted in the first position.
  "content": <ContentData> A content data object.
}

delete_content

{
  "type": "delete_content"
  "section_id": <SectionId> The unique identifier of the section where the content is to be deleted.
  "content_id": <ContentId> The unique identifier of the content to be deleted.
}

update_content

{
  "type": "update_content"
  "section_id": <SectionId> The unique identifier of the section where the content is to be updated.
  "content_id": <ContentId> The unique identifier of the content to be updated.
  "value": <ContentDataValue> The value for the built-in setting of the content.
  "settings": <SettingsData> A settings data object.
}

insert_block

{
  "type": "insert_block"
  "section_id": <SectionId> The unique identifier of the section where the block is to be inserted.
  "after": <ContentId> The unique identifier of the block preceding the block being inserted. null if the block is to be inserted in the first position.
  "block": <BlockData> A block data object.
}

delete_block

{
  "type": "delete_block"
  "section_id": <SectionId> The unique identifier of the section where the block is to be deleted.
  "block_id": <BlockId> The unique identifier of the block to be deleted.
}

update_block

{
  "type": "update_block"
  "section_id": <SectionId> The unique identifier of the section where the block is to be updated.
  "block_id": <BlockId> The unique identifier of the block to be updated.
  "settings": <SettingsData> A settings data object.
}

Sign up for a Partner account to get started.

Sign up