Backend API

Content

Content models are a layer above data models and have a simpler configuration syntax and allow for field values to be editable in the dashboard. They provide most of the functionality you'd expect from a dedicated CMS—with the additional benefit of making content available in the same API as standard models like products. While data models are limited to primitive field types like string, content models can define input UIs for fields like phone_number or url to provide a better editing experience. This ensures that the data is entered in the correct format.

See the Data model customization guide for details on how to work with content models.

Content models can be created manually from the Swell dashboard, or installed automatically by Swell Apps. See the Apps content reference for more details.

The content model

Fields

id

stringauto

Unique identifier for the model.

label

string

Plural name of the content model collection.

name

stringrequiredauto

System name of the model. Defaults to [collection].[root].

collection

stringrequired

Specifies the model collection to create or enhance. The collection may be entirely new to the store or to an app that defines it, or may refer to a standard model such as products.

You may specify a namespace for the model which becomes part of its API endpoint, for example collection: content/testimonials would result in an API endpoint such as /content/testimonials. Also note, any content model defined in the content namespace is automatically made public, unless public: false is set.

fields

array of fieldrequired

Content fields and their properties applied for each record of a collection.

public

boolean

Indicates that collection records are accessible by a public API call.

views

array of view

Content views allowing you to configure different layouts for list and record pages. List views allow you to add fields and filters to collection lists, while record views allows you to add fields to record pages.

defaults

objectauto

Aggregate global default values derived from field defaults. These values are automatically applied to API responses when using the $content: true operator.

source_type

enumrequiredauto

Indicates the source of the content model, app or custom. The value is automatically set to custom when created from the Swell dashboard.

Possible enum values:

appcustom

app_id

objectId

ID of a Swell App that defined this model, if applicable.

date_created

dateauto

Date the model was created.

date_updated

dateauto

Date the model was last updated.

The content model
{
  "collection": "reviews",
  "fields": [
    {
      "id": "account",
      "label": "Reviewer",
      "type": "customer_lookup",
      "description": "The customer who wrote the review",
      "required": true
    },
    {
      "id": "product",
      "label": "Product",
      "type": "product_lookup",
      "description": "The product being reviewed",
      "required": true
    },
    {
      "id": "title",
      "label": "Review title",
      "type": "text",
      "description": "The title of the review",
      "required": true
    },
    {
      "id": "body",
      "label": "Review body",
      "type": "long_text",
      "description": "The body of the review",
      "required": true
    },
    {
      "id": "rating",
      "label": "Rating",
      "type": "slider",
      "unit": "stars",
      "min": 1,
      "max": 5,
      "description": "Rating (1-5) of the reviewed product",
      "admin_span": 1,
      "required": true
    },
    {
      "id": "images",
      "label": "Images",
      "type": "image",
      "description": "Images associated with the review",
      "multi": true,
      "conditions": {
        "$settings.images.enabled": true
      }
    },
    {
      "id": "status",
      "label": "Status",
      "type": "select",
      "description": "Admin status of the review",
      "default": "submitted",
      "admin_span": 2,
      "options": [
        {
          "label": "Submitted",
          "value": "submitted"
        },
        {
          "label": "Approved",
          "value": "approved"
        },
        {
          "label": "Rejected",
          "value": "rejected"
        }
      ]
    },
    {
      "id": "rejected_reason",
      "label": "Rejected reason",
      "type": "long_text",
      "description": "Reason for rejecting the review, may be visible to the customer",
      "conditions": {
        "status": "rejected"
      }
    },
    {
      "id": "reward_amount",
      "label": "Reward amount",
      "type": "currency",
      "description": "Amount to reward the customer for writing the review",
      "admin_span": 1,
      "conditions": {
        "$settings.rewards.enabled": true,
        "status": "approved",
        "reward_disabled": { "$ne": true },
        "rewarded": { "$ne": true }
      }
    },
    {
      "id": "reward_disabled",
      "label": "Disable reward",
      "type": "toggle",
      "conditions": {
        "$settings.rewards.enabled": true,
        "status": "approved",
        "rewarded": { "$ne": true }
      }
    },
    {
      "id": "verified_buyer",
      "label": "Verified buyer",
      "type": "toggle",
      "description": "Indicates the reviewer has purchased the product",
      "conditions": {
        "$settings.verified.enabled": true
      }
    },
    {
      "id": "featured",
      "label": "Featured",
      "type": "toggle",
      "description": "Indicates the review may be featured in your storefront",
      "conditions": {
        "$settings.featured.enabled": true
      }
    },
    {
      "type": "field_row",
      "fields": [
        {
          "id": "like_count",
          "label": "Like count",
          "type": "number",
          "description": "Indicates the number of likes the review has received",
          "readonly": true
        },
        {
          "id": "dislike_count",
          "label": "Dislike count",
          "type": "number",
          "description": "Indicates the number of dislikes the review has received",
          "readonly": true
        }
      ]
    },
    {
      "id": "comments",
      "label": "Comments",
      "type": "child_collection",
      "fields": [
        {
          "id": "account",
          "label": "Customer",
          "type": "customer_lookup",
          "description": "The customer who wrote the comment",
          "required": true
        },
        {
          "id": "body",
          "label": "Comment body",
          "type": "long_text",
          "description": "The body of the comment",
          "required": true
        },
        {
          "id": "status",
          "label": "Status",
          "type": "select",
          "description": "Admin status of the comment",
          "default": "submitted",
          "options": [
            {
              "label": "Submitted",
              "value": "submitted"
            },
            {
              "label": "Approved",
              "value": "approved"
            },
            {
              "label": "Rejected",
              "value": "rejected"
            }
          ]
        },
        {
          "id": "rejected_reason",
          "label": "Rejected reason",
          "type": "long_text",
          "description": "Reason for rejecting the comment, may be visible to the customer",
          "conditions": {
            "status": "rejected"
          }
        },
        {
          "id": "verified_buyer",
          "label": "Verified buyer",
          "type": "toggle",
          "description": "Indicates the user has purchased the product",
          "conditions": {
            "$settings.verified.enabled": true
          }
        },
        {
          "type": "field_row",
          "fields": [
            {
              "id": "like_count",
              "label": "Like count",
              "type": "number",
              "description": "Indicates the number of likes the comment has received",
              "readonly": true
            },
            {
              "id": "dislike_count",
              "label": "Dislike count",
              "type": "number",
              "description": "Indicates the number of dislikes the comment has received",
              "readonly": true
            }
          ]
        }
      ]
    }
  ],
  "views": [
    {
      "id": "list",
      "nav": {
        "parent": "products",
        "label": "Honest Reviews"
      },
      "tabs": [
        {
          "id": "approved",
          "label": "Approved",
          "query": {
            "status": "approved"
          }
        },
        {
          "id": "rejected",
          "label": "Rejected",
          "query": {
            "status": "rejected"
          }
        },
        {
          "id": "verified",
          "label": "Verified buyers",
          "query": {
            "verified_buyer": true
          }
        }
      ],
      "fields": [
        {
          "id": "title"
        },
        {
          "id": "product"
        },
        {
          "id": "body",
          "truncated": 100
        },
        {
          "id": "rating",
          "template": "{{ rating }} {{ rating | default: 1 | pluralize: 'star','stars' }}"
        },
        {
          "id": "account"
        },
        {
          "id": "status"
        },
        {
          "id": "comments"
        },
        {
          "id": "date_created",
          "label": "Submitted"
        },
        {
          "id": "reward_amount",
          "conditions": {
            "$settings.rewards.enabled": true
          }
        },
        {
          "id": "verified_buyer",
          "conditions": {
            "$settings.verified.enabled": true
          }
        },
        {
          "id": "featured",
          "conditions": {
            "$settings.featured.enabled": true
          }
        }
      ]
    },
    {
      "id": "new",
      "fields": [
        {
          "type": "field_row",
          "fields": [
            {
              "id": "account"
            },
            {
              "id": "product"
            }
          ]
        },
        {
          "id": "title"
        },
        {
          "id": "body"
        },
        {
          "id": "rating"
        },
        {
          "id": "images"
        },
        {
          "id": "status"
        },
        {
          "id": "rejected_reason"
        },
        {
          "id": "reward_amount"
        },
        {
          "id": "reward_disabled"
        },
        {
          "id": "verified_buyer"
        },
        {
          "id": "featured"
        },
        {
          "id": "comments"
        }
      ]
    },
    {
      "id": "edit",
      "title": "{{ title }}",
      "subtitle": "By {{ account.name }}",
      "fields": [
        {
          "type": "field_row",
          "fields": [
            {
              "id": "account"
            },
            {
              "id": "product"
            }
          ]
        },
        {
          "id": "title"
        },
        {
          "id": "body"
        },
        {
          "id": "rating"
        },
        {
          "id": "images"
        },
        {
          "id": "status"
        },
        {
          "id": "rejected_reason"
        },
        {
          "id": "reward_amount"
        },
        {
          "id": "rewarded_amount",
          "readonly": true,
          "type": "currency",
          "default": "{{ reward_amount }}",
          "conditions": {
            "rewarded": true,
            "reward_amount": { "$gt": 0 }
          }
        },
        {
          "id": "reward_disabled"
        },
        {
          "id": "verified_buyer"
        },
        {
          "id": "featured"
        },
        {
          "id": "comments"
        },
        {
          "type": "field_row",
          "conditions": {
            "$settings.reactions.enabled": true
          },
          "fields": [
            {
              "id": "like_count",
              "admin_span": 1
            },
            {
              "id": "dislike_count",
              "admin_span": 1
            }
          ]
        }
      ]
    }
  ]
}
← Back: ModelsNext: Events →
© 2025 Swell
Terms of servicePrivacy policy