API Reference
Last updated

Theme API Reference

This guide covers the API endpoints for managing themes and templates programmatically.

Theme Management API

Get Company Themes

Returns list of all themes available to the company (root + company-specific).

GET /api/application_themes

Create Company Theme

Creates a new theme for the company.

POST /api/application_themes

Request Body:

{
  "name": "Custom Company Theme",
  "description": "Customized theme for our brand",
  "clone_from_id": 123,
  "variables": {
    "primary_color": "#ff6b6b",
    "secondary_color": "#4ecdc4"
  }
}
FieldTypeDescription
namestringTheme name (required)
descriptionstringTheme description
clone_from_idintegerID of theme to clone from
variablesobjectCSS variables as key-value pairs

Update Theme

Updates theme properties.

PUT /api/application_themes/{theme_id}

Request Body:

{
  "name": "Updated Theme Name",
  "variables": {
    "primary_color": "#e74c3c",
    "font_family": "'Open Sans', sans-serif"
  },
  "custom_stylesheet": ".custom-class { margin: 20px; }"
}

Publish Theme

Activates the theme for the company, deactivating the current active theme.

POST /api/application_themes/{theme_id}/publish

Template Management API

Get Theme Templates

Returns templates for a specific theme.

GET /api/application_themes/{theme_id}/templates

Query Parameters:

ParameterTypeDescription
themeable_typestringFilter by template type (product, home_page, etc.)
statusstringFilter by status (draft, active)

Create Template

Creates a new template within a theme.

POST /api/application_themes/{theme_id}/templates

Request Body:

{
  "name": "Custom Product Template",
  "themeable_type": "product",
  "content": "<div>{{ product.name }}</div>",
  "format": "liquid",
  "applicable": "specific"
}
FieldTypeDescription
namestringTemplate name (required)
themeable_typestringTemplate type (required)
contentstringTemplate code (Liquid or JSON)
formatstringliquid or json
applicablestringeverything or specific

Update Template

Updates an existing template.

PUT /api/application_theme_templates/{template_id}

Request Body:

{
  "content": "<h1>{{ product.name }}</h1>",
  "head": "<meta name='description' content='{{ product.description }}' />",
  "stylesheet": ".product-title { color: red; }"
}

Make Template Default

Sets this template as the default for its themeable_type within the theme.

POST /api/application_theme_templates/{template_id}/make_default

Template Preview API

Preview Template

Returns rendered HTML of the template with sample or specified content.

GET /api/application_theme_templates/{template_id}/preview

Query Parameters:

ParameterTypeDescription
versionintegerSpecific version to preview
record_idintegerID of content item to preview with

Themeable Types

Available values for themeable_type:

TypeDescription
productIndividual product pages
mediumMedia post pages
enrollment_packCourse/enrollment pages
shop_pageShop/catalog pages
navbarNavigation header
libraryLibrary/playlist pages
pageCustom pages
componentsReusable components
sectionsTemplate sections
localesLocalization templates
footerPage footer
layoutsPage wrapper layouts
category_pageCategory browsing
collection_pageCollection browsing
cart_pageShopping cart
configTheme configuration
home_pageHomepage layout
mysiteMySite pages
join_pageRegistration pages

Error Responses

Theme Validation Errors (422)

{
  "status": "unprocessable_entity",
  "errors": {
    "variables": ["Variables must be valid JSON"],
    "name": ["Name cannot be blank"]
  }
}

Template Validation Errors (422)

{
  "status": "unprocessable_entity",
  "errors": {
    "content": ["Content cannot be blank"],
    "themeable_type": ["Themeable type is not included in the list"]
  }
}

Theme Not Found (404)

{
  "status": "not_found",
  "errors": {
    "base": ["Theme not found"]
  }
}

Active Theme Deletion Error (422)

{
  "status": "unprocessable_entity",
  "errors": {
    "base": ["Cannot delete a published theme"]
  }
}

Ruby Model Examples

Find Company's Active Theme

company = Company.find(123)
active_theme = company.current_theme

Clone a Root Theme

root_theme = ApplicationTheme.root.find_by(name: 'fluid')
company_theme = root_theme.deep_clone(company.id)
company_theme.name = "Custom Fluid Theme"
company_theme.save!

Customize Theme Variables

company_theme.variables = {
  primary_color: '#ff6b6b',
  secondary_color: '#4ecdc4',
  font_family: 'Inter, sans-serif'
}.to_json
company_theme.save!

Create a Custom Template

custom_template = company_theme.application_theme_templates.create!(
  name: 'Custom Product Layout',
  themeable_type: :product,
  content: '<div class="custom-product">{{ product.name }}</div>',
  format: :liquid
)

# Make it the default
custom_template.make_default
Previous page
Next page