Metafields and metaobjects can be owned by merchants or apps. Merchant owned metafields and metaobjects are open to merchants and developers, which means there are no restrictions on who can read, write, or modify them. However, you can use reserved namespaces to gain control over your application's data.

## Reserved prefixes

There is a reserved prefix your app can prepend to metafield namespaces and metaobject types to take ownership of them. Using a reserved namespace ensures that your app exclusively controls all structure, data, permissions, and optional features.

> Tip:
> Learn more about [permissions](/docs/apps/build/custom-data/permissions).

## Create metafield definitions with reserved namespaces

To establish metafield definitions within a reserved namespace, prefix the namespace with `$app`. The API will automatically convert this to a fully qualified reserved namespace like `app--{your-app-id}[--{optional-namespace}]`:

- **`app`**: Indicates that this is a reserved namespace for an app.
- **`{your-app-id}`**: Your app's unique API client ID.
- **`{optional-namespace}`**: An optional namespace of your choosing.

For example, if your app's API client ID is `123456`, you can create both:

- `$app` → `app--123456`
- `$app:influencer` → `app--123456--influencer`

> Note
> All APIs default to using a reserved namespace `$app`.

**Example:**

The following example creates a product metafield definition under a reserved namespace:


```graphql
mutation {
  metafieldDefinitionCreate(definition: {
    name: "Ingredients",
    key: "ingredients",
    description: "List of ingredients used in the product.",
    type: "list.single_line_text_field",
    ownerType: "PRODUCT"
  }) {
    createdDefinition {
      name
      namespace
      key
    }
  }
}
```



```json
{
  "metafieldDefinitionCreate": {
    "createdDefinition": {
      "name": "Ingredients",
      "namespace": "app--123456",
      "key": "ingredients"
    },
  }
}
```




## Create metaobject definitions with reserved types

Similar to [metafields](#create-metafield-definitions-with-reserved-namespaces), you can create metaobject definitions owned by your app by using the reserved prefix syntax for the metaobject type.

The following example creates a product highlight metaobject definition under a reserved namespace, while overriding the default permissions to grant the merchant [read and write access](/docs/apps/build/custom-data/permissions):



```graphql
mutation {
  metaobjectDefinitionCreate(definition: {
    name: "Product Highlight",
    type: "$app:product_highlight",
    access: {
      admin: MERCHANT_READ_WRITE,
      storefront: PUBLIC_READ,
    },
    displayNameKey: "title",
    fieldDefinitions: [
      {
        key: "title",
        type: "single_line_text_field",
      },
      {
        key: "description",
        type: "multi_line_text_field",
      },
      {
        key: "creative",
        type: "file_reference",
      },
    ]
  }) {
    metaobjectDefinition {
      id
      type
      permissions
      fieldDefinitions {
        key
        type
      }
    }
  }
}
```



```json
{
  "data": {
    "metaobjectDefinitionCreate": {
      "metaobjectDefinition": {
        "id": "gid://Shopify/MetaobjectDefinition/1",
        "type": "app--123456--product_highlight",
        "permissions": {
          "admin": "MERCHANT_READ_WRITE",
          "storefront": "PUBLIC_READ",
        },
        "fieldDefinitions": [
          { "key": "title", "type": "single_line_text_field" },
          { "key": "description", "type": "multi_line_text_field" },
          { "key": "creative", "type": "file_reference" },
        ],
      }
    }
  }
}
```




## App-data metafields

An app-data metafield is a metafield that is tied to a particular app installation and can only be accessed by that app. App-data metafields can't be overwritten by other apps or by merchants, and can be accessed using GraphQL. You can access app-data metafields using the `metafields` property on the [`app` object in Liquid](/docs/api/liquid/objects/app).

Using app-data metafields, you can provide different levels of features to users depending on their app payment plan by using app-data metafields and [conditional app blocks](/docs/apps/build/online-store/theme-app-extensions/configuration#conditional-app-blocks). You can also store a client ID or client secret in app-data metafields.

The following steps demonstrate how to create and manage app-data metafields, which are metafields that are tied to a specific app installation. You'll learn how to securely store app-specific data that can't be modified by other apps or merchants.

### Requirements

- Your app can make [authenticated requests](/docs/api/admin-graphql#authentication) to the GraphQL Admin API.

### Step 1: Retrieve the app installation ID
First, use the [`currentAppInstallation`](/docs/api/admin-graphql/latest/queries/currentAppInstallation) query to retrieve the ID of the [`AppInstallation`](/docs/api/admin-graphql/latest/objects/AppInstallation) object associated with your app. In the next step, you'll use this ID to create a new app-data metafield.

```graphql
query {
  currentAppInstallation {
    id
  }
}
```

```json
{
  "data": {
    "currentAppInstallation": {
      "id": "gid://shopify/AppInstallation/123456"
    }
  }
}
```



### Step 2: Create an app-data metafield

To create an app-data metafield, use the [`metafieldSet`](/docs/api/admin-graphql/current/mutations/metafieldsSet) mutation, setting `ownerID` to the app installation ID from the [previous step](#step-1-retrieve-the-app-installation-id):

```graphql
mutation CreateAppDataMetafield($metafieldsSetInput: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafieldsSetInput) {
    metafields {
      id
      namespace
      key
    }
    userErrors {
      field
      message
    }
  }
}
```

```json
{
  "metafieldsSetInput": [
    {
      "namespace": "secret_keys",
      "key": "api_key",
      "type": "single_line_text_field",
      "value": "aS1hbS1hLXNlY3JldC1hcGkta2V5Cg==",
      "ownerId": "gid://shopify/AppInstallation/3"
    }
  ]
}
```



After you've created a metafield, you can access its value using the [`metafield` field on the`AppInstallation` object](/docs/api/admin-graphql/latest/objects/AppInstallation).

## Next steps

- Learn about [defining metafields](/docs/apps/build/custom-data/metafields/definitions) to create custom fields.
- Learn about [managing metaobjects](/docs/apps/build/custom-data/metaobjects/manage-metaobjects) to create custom objects.
- Learn about [permissions](/docs/apps/build/custom-data/permissions) for your definitions.
- Use an app-data metafield to implement a [conditional app block](/docs/apps/build/online-store/theme-app-extensions/configuration#conditional-app-blocks).