Section themes REST API

MasterPage

Rules for MasterPage

  • Only one master page per type can be created.
  • When a master page has default=true, new pages that get created are automatically assigned that master page’s ID as their master_page_id.
  • The sections property must include the pages/#{type}.liquid page section file, whose ID must 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.

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
POST /master_pages.json Creates a new master page.
{
  "master_page": { … }
}
PUT /master_pages/#{id}.json Updates a master page page.
{
  "master_page": { … }
}

SystemPage

Rules for SystemPage

  • System pages are automatically created on shop creation and can't be created or deleted through the API.
  • When the sections property is not null, it must include the pages/#{type}.liquid page section file, whose ID must be page.
  • When the sections property is null, or when it is not null but the main theme does not include a pages/#{type}.liquid page section file, the page is rendered with the templates/#{type}.liquid theme template file.
  • When the sections property is not null, the sections are rendered instead of the theme template.
  • When the theme_frame_id property is null, and the main theme includes a config/frames.json, the page is rendered with the theme frame whose ID is #{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
  • 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 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.

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 Updates a system page.
{
  "system_page": { … }
}

ProductPage

Rules for ProductPage

  • 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.
  • 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 theme_frame_id property is null, and the main theme includes a config/frames.json, the page is rendered with 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.

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 Updates a product page.
{
  "product_page": { … }
}
PATCH /product_pages/#{id}/overrides.json Appends an override to the product page. Overrides that cancel each other are automatically deleted.
{
  "overrides": [<OverrideData>],
  "master_page_version": "a4f9d3c7"
}
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

Rules for CollectionPage

  • 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.
  • 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 theme_frame_id property is null, and the main theme includes a config/frames.json, the page is rendered with 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.

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 Updates a collection page.
{
  "collection_page": { … }
}
PATCH /collection_pages/#{id}/overrides.json Appends an override to the collection page. Overrides that cancel each other are automatically deleted.
{
  "overrides": [<OverrideData>],
  "master_page_version": "a4f9d3c7"
}
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

Rules for Blog

  • 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.
  • When the sections property is not null, the sections are rendered instead of the theme template.
  • When the theme_frame_id property is null, and the main theme includes a config/frames.json, the page is rendered with the theme frame whose ID is blog, otherwise whose ID is default.

New added 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 article page should be rendered with.

Article

Rules for Article

  • 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.
  • 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 theme_frame_id property is null, and the main theme includes a config/frames.json, the page is rendered with the theme frame whose ID is article, otherwise whose ID is default.

New added 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 added endpoint

PATCH /articles/#{id}/overrides.json Appends an override to the article. Overrides that cancel each other are automatically deleted.
{
  "overrides": [<OverrideData>],
  "master_page_version": "a4f9d3c7"
}
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

Rules for Page

  • 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.
  • 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 theme_frame_id property is null, and the main theme includes a config/frames.json, the page is rendered with the theme frame whose ID is page, otherwise whose ID is default.

New added 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 added endpoint

PATCH /pages/#{id}/overrides.json Appends an override to the page. Overrides that cancel each other are automatically deleted.
{
  "overrides": [<OverrideData>],
  "master_page_version": "a4f9d3c7"
}
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.
  • A section may not have content and blocks at the same time.
{
"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 ordered array of content data objects or the boolean false for content sections that don’t accept content. Not supported by page sections.
"blocks": [<Blockdata>] An ordered array of block data objects.
"settings": [<Settingsdata>] A settings data object.
}

<ContentData>

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

<ContentDataValue>

Content type
text
{
  "title": <String>
  "content": <RichTextString>
}
image
{
  "url": <ShopImageUrl>
  "link": <ShopifyUrl>
  "caption": <RichTextString>
}
video_url
{
  "url": <VideoUrl>
  "cover": <ShopImageUrl>
  "caption": <RichTextString>
}
product
{
  "id": <ProductId>
}
collection
{
  "id": <CollectionId>
}
blog
{
  "id": <BlogId>
}
article
{
  "id": <ArticleId>
}

<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 values of the content object.
"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