---
title: Manifest
description: >
  Learn how to configure your Shop Mini using the manifest.json file. The
  manifest defines critical properties like description, permissions, scopes,
  and trusted domains.
api_name: shop-minis
source_url:
  html: 'https://shopify.dev/docs/api/shop-minis/manifest-file'
  md: 'https://shopify.dev/docs/api/shop-minis/manifest-file.md'
---

# Manifest

Learn how to configure your Shop Mini using the manifest.json file. The manifest defines critical properties like description, permissions, scopes, and trusted domains.

***

## Overview

Every Shop Mini requires a `manifest.json` file in the src folder of the project. This file defines the configuration and capabilities of your Mini, including what permissions it needs, what user data it can access, and which external domains it can communicate with.

The manifest is validated during the submission process and must be properly configured for your Mini to function correctly.

***

## Manifest Structure

Here's an example of a complete `manifest.json` file:

## manifest.json

```json
{
  "name": "My Mini",
  "description": "A brief description of your mini that explains its purpose and functionality",
  "handle": "my-mini-handle",
  "permissions": ["CAMERA", "MICROPHONE", "MOTION"],
  "scopes": ["profile", "orders"],
  "trusted_domains": [
    "api.example.com/v1",
    "storage.googleapis.com/my-mini-bucket",
    "cdn.example.com/assets"
  ]
}
```

***

## Permissions

The `permissions` field is an array that specifies which native device capabilities your Mini requires. These permissions are requested from the user when your Mini attempts to use them.

### Available Permissions

* **`CAMERA`** - Access to the device camera for taking photos or videos
* **`MICROPHONE`** - Access to the device microphone for audio recording
* **`MOTION`** - Access to device motion sensors (accelerometer, gyroscope)

### Example

```json
{
  "permissions": ["CAMERA", "MICROPHONE"]
}
```

Caution

Only request permissions that are essential to your Mini's core functionality. Requesting unnecessary permissions may delay approval during the review process.

***

## Scopes

The `scopes` field is an array that defines what user data your Mini can access through the Shop Minis SDK. Some hooks in the SDK require specific scopes to be declared in the manifest before they can be used.

### Available Scopes

#### User Scopes

* **`openid`** - OpenID Connect authentication. Required for generating user tokens.
* **`profile`** - Read access to user's buyer profile.
* **`user_settings:read`** - Read access to the current user.

#### Product Scopes

* **`products:recent:read`** - Read access to the user's recently viewed products.
* **`products:recommendations:read`** - Read access to personalized product recommendations for the user.

#### Shop Scopes

* **`shops:recent:read`** - Read access to the user's recently viewed shops.
* **`shops:follows:read`** - Read access to shops the user follows.
* **`shops:follows:write`** - Write access to follow or unfollow shops.
* **`shops:recommendations:read`** - Read access to personalized shop recommendations for the user.

#### Order Scopes

* **`orders`** - Access to the user's order history and details.

#### Product List Scopes

* **`product_list:read`** - Read access to the user's collections (favorites, wishlists, etc.).
* **`product_list:write`** - Write access to create, update, or delete collections.
* **`product_list_item:write`** - Write access to add or remove items from collections.

### Example

```json
{
  "scopes": ["profile", "orders"]
}
```

Note

Always follow the principle of least privilege - only request scopes that are necessary for your Mini's functionality. Review the [Guidelines](./guidelines) for more information on data privacy requirements.

***

## Trusted Domains

The `trusted_domains` field is an array of domains that your Mini is allowed to communicate with. This is a critical security feature that restricts network requests to approved domains only.

### Usage

Trusted domains are required for:

* **Network requests** - Any `fetch()` calls to external APIs
* **Image sources** - Loading images from external URLs
* **Video sources** - Loading videos from external URLs
* **Other external resources** - Any content loaded from outside your Mini's bundle

### Domain Format

* Do not include the protocol (e.g., `https://`)
* You can include paths to be more specific
* Subdomains must be listed separately
* Do not include trailing slashes
* **Be as specific as possible** - For example, if using Google Cloud Storage, include the full path to your specific bucket rather than just the domain

### Example

```json
{
  "trusted_domains": [
    "api.example.com/v1",
    "storage.googleapis.com/my-mini-bucket",
    "cdn.example.com/assets"
  ]
}
```

Caution

Your Mini will not be able to make requests to any domain not listed in this array. Make sure to include all domains you need before submitting your Mini for review.

Tip

Be as specific as possible with your paths. Instead of `storage.googleapis.com`, use `storage.googleapis.com/my-mini-bucket` to limit access to only your bucket.

***

## Handle

The `handle` field is a unique identifier for your Mini. This value is automatically assigned when you create your Mini through the Shop Minis platform.

### Characteristics

* Automatically generated during Mini creation
* Must be unique across all Shop Minis
* Used internally by Shop to identify your Mini
* Cannot be changed after initial assignment
* Used to deeplink into your Mini (shop.app/mini/my-mini-handle)

### Example

```json
{
  "handle": "my-awesome-mini"
}
```

Note

You typically don't need to manually set this field. It's automatically populated when you initialize a new Mini project using the Shop Minis CLI.

***

## Description

The `description` field provides a brief summary of your Mini's purpose and functionality. This description is displayed to users in various places within the Shop app to help them understand what your Mini offers.

### Characteristics

* Should be concise and informative (recommended 30-50 characters)
* Helps users discover and understand your Mini's value proposition
* Used in search results and Mini details

### Example

```json
{
  "description": "Track your outfits every day"
}
```

### Best Practices

* **Be specific:** Clearly state what unique value your Mini provides
* **Keep it concise:** Aim for 30-50 characters maximum
* **Use action words:** Start with verbs like "Discover," "Shop," "Track," or "Explore"
* **Highlight key features:** Mention the main benefit or differentiator of your Mini

***

## Best Practices

### Minimize Permissions and Scopes

Only request the permissions and scopes that are absolutely necessary for your Mini's core functionality. This improves user trust and speeds up the review process.

### Keep Trusted Domains Updated

As your Mini evolves, make sure to update the `trusted_domains` list if you add new external services or APIs. Missing domains will cause runtime errors.

### Validation

Test your manifest configuration thoroughly during development to catch any issues before submission. The Shop Minis SDK will validate your manifest and provide warnings for common issues.

***