---
title: Use metaobject capabilities
description: Learn about optional features available for metaobjects.
source_url:
  html: 'https://shopify.dev/docs/apps/build/metaobjects/use-metaobject-capabilities'
  md: >-
    https://shopify.dev/docs/apps/build/metaobjects/use-metaobject-capabilities.md
api_name: admin
---

# Use metaobject capabilities

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

* **[`publishable`](#draft-custom-content)**: Set metaobjects as either `DRAFT` or `ACTIVE` to control visibility in storefronts.
* **[`translatable`](#make-your-metaobjects-translatable)**: Allow metaobject translations through [Shopify's translation APIs](https://shopify.dev/docs/apps/build/markets/manage-translated-content).
* **[`renderable`](#render-metaobjects-as-web-pages)**: Set SEO metadata attributes on your metaobjects.
* **[`onlineStore`](#make-your-metaobjects-render-web-pages-in-the-online-store)**: Assign a theme template and define a URL to make your metaobjects render web pages in the online store.

***

## Draft 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 permissions](https://shopify.dev/docs/apps/build/metaobjects#permissions).

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

## shopify.app.toml

##### TOML

```toml
[metaobjects.app.custom_article]
name = "Custom Article"
access.admin = "merchant_read_write"
access.storefront = "public_read"
capabilities.publishable = true

[metaobjects.app.custom_article.fields.title]
name = "Title"
type = "single_line_text_field"

[metaobjects.app.custom_article.fields.body]
name = "Body"
type = "rich_text_field"

[metaobjects.app.custom_article.fields.author]
name = "Author"
type = "single_line_text_field"
```

##### GraphQL

```graphql
mutation {
  metaobjectDefinitionCreate(definition: {
    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" }
    ]
  }) {
    metaobjectDefinition {
      id
      type
      capabilities {
        publishable {
          enabled
        }
      }
      fieldDefinitions {
        key
        name
        type {
          name
        }
      }
    }
  }
}
```

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

```graphql
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

```json
{
  "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

```json
{
  "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

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

## Variables

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

## JSON response

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

***

## Make your metaobjects translatable

The `translatable` capability allows the fields of a metaobject to be translated. You can enable this capability by setting `translatable` to `true` when creating or updating a metaobject definition.

## Update a Custom Article metaobject to be translatable

## GraphQL mutation

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

## Variables

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

## JSON response

```json
{
  "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](https://shopify.dev/docs/apps/build/markets/manage-translated-content) 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

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

## JSON response

```json
{
  "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

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

## Variables

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

## JSON response

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

***

## Render 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`](https://shopify.dev/docs/api/liquid/objects/sitemap) for Liquid storefronts and accessible using the [`Sitemap`](https://shopify.dev/docs/api/storefront/latest/queries/sitemap) query in the Storefront API.

You can enable this capability by setting `renderable` to `true` when creating or updating a metaobject definition.

In the following example, a metaobject definition is created with `renderable` set to `true` to enable this capability and sets the meta title and description attributes to the `title` and `body` fields respectively:

## shopify.app.toml

##### TOML

```toml
[metaobjects.app.renderable_content]
name = "Renderable Content"
access.admin = "merchant_read_write"
access.storefront = "public_read"
capabilities.renderable = true

[metaobjects.app.renderable_content.fields.title]
name = "Title"
type = "single_line_text_field"

[metaobjects.app.renderable_content.fields.body]
name = "Body"
type = "rich_text_field"
```

##### GraphQL

```graphql
mutation {
  metaobjectDefinitionCreate(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" }
    ]
  }) {
    metaobjectDefinition {
      id
      name
      capabilities {
        renderable {
          enabled
          data {
            metaTitleKey
            metaDescriptionKey
          }
        }
      }
    }
  }
}
```

***

## Make your metaobjects render web pages in the Online Store

**Online store capability support in TOML configuration:**

Currently, the `onlineStore` capability is not supported in TOML configuration.

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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metaobjectdefinitioncreate) or [`metaobjectDefinitionUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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

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

## Variables

```json
{
  "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

```json
{
  "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"
            }
          }
        }
      }
    }
  }
}
```

***