Skip to main content

Use metaobject capabilities

Capabilities power optional features for metaobject definitions. You can enable the following capabilities:

  • publishable: Set metaobjects as either DRAFT or ACTIVE to control visibility in storefronts.
  • translatable: Allow metaobject translations through Shopify's translation APIs.
  • renderable: Set SEO metadata attributes on your metaobjects.
  • onlineStore: Assign a theme template and define a URL to make your metaobjects render web pages in the online store.

Anchor to Draft custom contentDraft custom content

The publishable capability enables users of your metaobject to set its status to either DRAFT or ACTIVE. This can be useful for providing users a way to stage their content before making it available to their storefronts - even if you defined it to be available to storefronts using access controls.

In the following example, the metaobjectDefinitionCreate mutation is called with publishable set to true to enable this capability:

Creating a new metaobject definition with publishable enabled

GraphQL Mutation

mutation($input: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $input) {
metaobjectDefinition {
id
type
capabilities {
publishable {
enabled
}
}
fieldDefinitions {
key
name
type {
name
}
}
}
}
}

Variables

{
"input" : {
"name": "Custom Article",
"type": "$app:custom_article",
"access": {
"admin": "MERCHANT_READ_WRITE",
"storefront": "PUBLIC_READ"
},
"capabilities": {
"publishable": {
"enabled": true
}
},
"fieldDefinitions": [
{ "key": "title", "name": "Title", "type": "single_line_text_field" },
{ "key": "body", "name": "Body", "type": "rich_text_field" },
{ "key": "author", "name": "Author", "type": "single_line_text_field" }
]
}
}

JSON response

{
"data": {
"metaobjectDefinitionCreate": {
"metaobjectDefinition": {
"id": "gid://shopify/MetaobjectDefinition/1",
"type": "app--12345--custom_article",
"capabilities": {
"publishable": {
"enabled": true
}
},
"fieldDefinitions": [
{ "key": "title", "name": "Title", "type": { "name": "single_line_text_field" } },
{ "key": "body", "name": "Body", "type": { "name": "rich_text_field" } },
{ "key": "author", "name": "Author", "type": { "name": "single_line_text_field" } }
]
}
}
}
}

Next, using the metaobjectCreate mutation, you'll notice that the default status for a created "Custom Article" metaobject is DRAFT.

Creating a Custom Article metaobject

GraphQL Mutation

mutation($input: MetaobjectCreateInput!) {
metaobjectCreate(metaobject: $input) {
metaobject {
handle
type
capabilities {
publishable {
status
}
}
title: field(key: "title") { value }
body: field(key: "body") { value },
author: field(key: "author") { value },
}
}
}

Variables

{
"input" : {
"type": "$app:product_highlight",
"fields": [
{
"key": "title",
"value": "Our fall guide"
}
{
"key": "body",
"value": "Here are some quick tips to starting fall off right."
}
{
"key": "author",
"value": "Jane Doe"
}
]
}
}

JSON response

{
"data": {
"metaobjectCreate": {
"metaobject": {
"handle": "our-fall-guide",
"type": "app--12345--custom_article",
"capabilities": {
"publishable": {
"status": "DRAFT",
}
},
"title": {
"value": "Our fall guide"
},
"body": {
"value": "Here are some quick tips to starting fall off right."
},
"author": {
"value": "Jane Doe"
}
}
}
}
}

To publish the custom article metaobject, you can use the metaobjectUpdate mutation and set the status to ACTIVE.

Publishing the custom article

GraphQL Mutation

mutation($input: MetaobjectCreateInput!) {
metaobjectUpdate(id: $id, metaobject: $metaobject) {
metaobject {
capabilities {
publishable {
status
}
}
}
}
}

Variables

{
"input" : {
"id": "gid://shopify/Metaobject/123",
"metaobject": {
"capabilities": {
"publishable": {
"status": "ACTIVE"
},
}
}
}
}

JSON response

{
"data": {
"metaobjectUpdate": {
"metaobject": {
"capabilities": {
"publishable": {
"status": "ACTIVE"
}
}
}
}
}
}

Anchor to Make your metaobjects translatableMake your metaobjects translatable

The translatable capability allows the fields of a metaobject to be translated. You can be enable this capability by setting translatable to true when performing a metaobjectDefinitionCreate or metaobjectDefinitionUpdate mutation.

Update a Custom Article metaobject to be translatable

GraphQL mutation

mutation($definition: MetaobjectDefinitionUpdate!, $id: ID!) {
metaobjectDefinitionUpdate(definition: $definition, id: $id) {
metaobjectDefinition {
id
name
capabilities {
translatable {
enabled
}
}
}
}
}

Variables

{
"id": "gid://shopify/MetaobjectDefinition/1234567",
"definition": {
"capabilities": {
"translatable": {
"enabled": true
}
}
}
}

JSON response

{
"data": {
"metaobjectDefinitionUpdate" {
"metaobjectDefinition": {
"id": "gid://shopify/MetaobjectDefinition/1234567",
"name": "Custom Article",
"capabilities": {
"translatable": {
"enabled": true
}
}
}
}
}
}

Once translatable has been enabled, you can use Shopify's translation APIs to register translations for fields on your metaobjects. For the "Custom Article" metaobject, you'll first need to retrieve the fields that can be translated through the translatableResources query:

Query for translatable metaobjects

GraphQL query

{
translatableResources(first: 1, resourceType: METAOBJECT) {
edges {
node {
resourceId
translatableContent {
key
value
digest
locale
}
}
}
}
}

JSON response

{
"data": {
"translatableResources": {
"edges": [
{
"node": {
"resourceId": "gid://shopify/Metaobject/123467",
"translatableContent": [
{
"key": "title",
"value": "Learn about hemming",
"digest": "dcf8d211f6633dac78dbd15c219a81b8931e4141204d18fba8c477afd19b75f9",
"locale": "en"
},
{
"key": "author",
"value": "Jane Doe",
"digest": "8e48350042b4ca04a7a4568774af71f921e7c9b561d9fac7860041e566218d25",
"locale": "en"
},
{
"key": "body",
"value": "Learn about hemming today!",
"digest": "7918dfe48350042b4ca04a7a4568774af71f921e7c9b561d9fac7860041e5662",
"locale": "en"
}
]
}
}
]
}
}
}

Then, you can register translations for any of the fields on the metaobject. For example, you can translate the title field by passing in the metaobject ID and using the digest for the title field:

Register a translation for the title field on the Custom Article metaobject

GraphQL mutation

mutation CreateTranslation($id: ID!, $translations: [TranslationInput!]!) {
translationsRegister(resourceId: $id, translations: $translations) {
userErrors {
message
field
}
translations {
locale
key
value
}
}
}

Variables

{
"id": "gid://shopify/Metaobject/1234567",
"translations": [
{
"key": "title",
"value": "Initiez-vous aux ourlets",
"locale": "fr",
"translatableContentDigest": "dcf8d211f6633dac78dbd15c219a81b8931e4141204d18fba8c477afd19b75f9"
}
]
}

JSON response

{
"data": {
"translationsRegister": {
"userErrors": [],
"translations": [
{
"locale": "fr",
"key": "title",
"value": "Initiez-vous aux ourlets"
}
]
}
}
}

Anchor to Render metaobjects as web pagesRender metaobjects as web pages

The renderable capability exposes metaobject SEO fields to Liquid and the Storefront API. Metaobjects with this capability are also included in the store's sitemap, which is sitemap.xml for Liquid storefronts and accessible using the Sitemap query in the Storefront API.

You can enable this capability by setting renderable to true when you perform a metaobjectDefinitionCreate or metaobjectDefinitionUpdate mutation.

In the following example, the metaobjectDefinitionCreate mutation is called with renderable set to true to enable this capability and sets the meta title and description attributes to the title and body fields respectively:

Creating a new metaobject definition with the renderable capability

GraphQL Mutation

mutation($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
id
name
capabilities {
renderable {
enabled
data {
metaTitleKey
metaDescriptionKey
}
}
}
}
}
}

Variables

{
"definition": {
"name": "Renderable Content",
"type": "$app:renderable_content",
"access": {
"admin": "MERCHANT_READ_WRITE",
"storefront": "PUBLIC_READ"
},
"capabilities": {
"renderable": {
"enabled": true,
"data": {
"metaTitleKey": "title",
"metaDescriptionKey": "body"
}
}
},
"fieldDefinitions": [
{ "key": "title", "name": "Title", "type": "single_line_text_field" },
{ "key": "body", "name": "Body", "type": "rich_text_field" }
]
}
}

JSON response

{
"data": {
"metaobjectDefinitionCreate": {
"metaobjectDefinition": {
"id": "gid://shopify/MetaobjectDefinition/54321",
"name": "app--12345--renderable_content",
"capabilities": {
"renderable": {
"enabled": true,
"data": {
"metaTitleKey": "title",
"metaDescriptionKey": "body"
}
}
}
}
}
}
}

Anchor to Make your metaobjects render web pages in the Online StoreMake your metaobjects render web pages in the Online Store

The onlineStore capability enables a metaobject to have an Online Store template and URL assigned to a metaobject definition. You can enable this capability by setting onlineStore to true when you perform a metaobjectDefinitionCreate or metaobjectDefinitionUpdate mutation.

In the following example, the metaobjectDefinitionCreate mutation is called with renderable set to true and onlineStore set to true to enable the web pages feature for the definition. The urlHandle is set to content resulting in the following URL for metaobject entries: /pages/content/{entry-handle}.

Creating a new metaobject definition with the web pages feature

GraphQL Mutation

mutation($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
id
name
capabilities {
renderable {
enabled
data {
metaTitleKey
metaDescriptionKey
}
}
onlineStore {
enabled
data {
urlHandle
}
}
}
}
}
}

Variables

{
"definition": {
"name": "Online Store Content",
"type": "$app:online_store_content",
"access": {
"admin": "MERCHANT_READ_WRITE",
"storefront": "PUBLIC_READ"
},
"capabilities": {
"renderable": {
"enabled": true,
"data": {
"metaTitleKey": "title",
"metaDescriptionKey": "body"
}
},
"onlineStore": {
"enabled": true,
"data": {
"urlHandle": "content"
}
}
},
"fieldDefinitions": [
{ "key": "title", "name": "Title", "type": "single_line_text_field" },
{ "key": "body", "name": "Body", "type": "rich_text_field" }
]
}
}

JSON response

{
"data": {
"metaobjectDefinitionCreate": {
"metaobjectDefinition": {
"id": "gid://shopify/MetaobjectDefinition/54321",
"name": "app--12345--online_store_content",
"capabilities": {
"renderable": {
"enabled": true,
"data": {
"metaTitleKey": "title",
"metaDescriptionKey": "body"
}
},
"onlineStore": {
"enabled": true,
"data": {
"urlHandle": "content"
}
}
}
}
}
}
}
Was this page helpful?