---
title: Admin UI extensions
description: >
Admin UI extensions make it possible to surface contextual app functionality
within the Shopify Admin interface.
api_version: 2024-04
api_name: admin-extensions
source_url:
html: 'https://shopify.dev/docs/api/admin-extensions/2024-04'
md: 'https://shopify.dev/docs/api/admin-extensions/2024-04.md'
---
# Admin UI extensions
With admin UI extensions, you can surface app functionality in the Shopify admin.
## Getting started
Use the Shopify CLI to [generate a new extension](https://shopify.dev/apps/tools/cli/commands#generate-extension) within your app.
If you already have a Shopify app, you can skip right to the last command shown here.
## Generate an extension
## CLI
```bash
# scaffold an app if you don't already have one:
npm init @shopify/app@latest --name my-app
# navigate to your app's root directory:
cd my-app
# generate a new extension:
npm run generate extension
# follow the steps to create a new
# extension in ./extensions.
```
***
## App authentication
Admin UI extensions can also make authenticated calls to your app's backend. When you use `fetch()` to make a request to your app's configured auth domain or any of its subdomains, an `Authorization` header is automatically added with a Shopify [OpenID Connect ID Token](https://shopify.dev/docs/api/app-bridge-library/reference/id-token). There's no need to manually manage session tokens.
Relative URLs passed to `fetch()` are resolved against your app's `app_url`. This means if your app's backend is on the same domain as your `app_url`, you can make requests to it using `fetch('/path')`.
## Make requests to your app's backend
## Get Product Data
```tsx
import {reactExtension, useApi, Text} from '@shopify/ui-extensions-react/admin';
import {useEffect, useState} from 'react';
// Get product info from app backend
async function getProductInfo(id) {
const res = await fetch(`/api/products/${id}`);
return res.json();
}
const TARGET = 'admin.product-details.block.render';
export default reactExtension(TARGET, () => );
function App() {
// Contextual "input" data passed to this extension:
const {data} = useApi(TARGET);
const productId = data.selected?.[0]?.id;
const [productInfo, setProductInfo] = useState();
useEffect(() => {
getProductInfo(productId).then(setProductInfo);
}, [productId]);
return Info: {productInfo?.title};
}
```
***
## Direct API access
You can make Shopify Admin API requests directly from your extension using the [query API](https://shopify.dev/docs/api/admin-extensions/api/standard-api#standardapi-propertydetail-query) or the standard [web fetch API](https://developer.mozilla.org/en-US/docs/Web/API/fetch)!
Any `fetch()` calls from your extension to Shopify's Admin GraphQL API are automatically authenticated by default. These calls are fast too, because Shopify handles requests directly.
Direct API requests use [online access](https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/online-access-tokens) mode by default. If you want to use [offline access](https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/offline-access-tokens) mode, you can set the `direct_api_mode` property to `offline` in your [app TOML file](https://shopify.dev/docs/apps/tools/cli/configuration#admin).
Note: Direct API can't be used to manage storefront access tokens.
[Note - Direct API can't be used to manage storefront access tokens.](https://shopify.dev/docs/api/admin-extensions#direct-api-access)
[Developer guide - Learn more about access scopes](https://shopify.dev/docs/api/usage/access-scopes)
## Query Shopify data
##### Fetch Product data
```tsx
import {reactExtension, useApi, Text} from '@shopify/ui-extensions-react/admin';
import {useEffect, useState} from 'react';
async function getProduct(id) {
const res = await fetch('shopify:admin/api/graphql.json', {
method: 'POST',
body: JSON.stringify({
query: `
query GetProduct($id: ID!) {
product(id: $id) {
title
}
}
`,
variables: {id},
}),
});
return res.json();
}
const TARGET = 'admin.product-details.block.render';
export default reactExtension(TARGET, () => );
function App() {
// Contextual "input" data passed to this extension:
const {data} = useApi(TARGET);
const [product, setProduct] = useState();
useEffect(() => {
const productId = data.selected?.[0]?.id;
getProduct(productId).then(({data}) => setProduct(data.product));
}, [data]);
return The selected product title is {product?.title};
}
```
##### Query Product data
```tsx
import {reactExtension, useApi, Text} from '@shopify/ui-extensions-react/admin';
import {useEffect, useState} from 'react';
const TARGET = 'admin.product-details.block.render';
export default reactExtension(TARGET, () => );
function App() {
// Contextual "input" data passed to this extension:
const {data, query} = useApi(TARGET);
const [product, setProduct] = useState();
useEffect(() => {
const productId = data.selected?.[0]?.id;
query(
`query GetProduct($id: ID!) {
product(id: $id) {
title
}
}
`,
{variables: {id: productId}},
).then(({data}) => setProduct(data.product));
}, [data]);
return The selected product title is {product?.title};
}
```
***
## Custom protocols
Custom protocols make it easier to navigate to common locations, and construct URLs.
Shopify Protocol
Use the `shopify:admin` protocol when you want to construct a URL with a root of the Shopify Admin.
App Protocol
Use the `app:` protocol to construct a URL for your app. Shopify will handle constructing the base URL for your app. This works for both embedded and non-embedded apps.
Extension Protocol
Triggers an action extension from a block extension using the `extension:` protocol. The `extensionTarget` is the target of the action extension. The handle is the handle of the action extension that will be opened.
Relative Urls
Relative urls are relative to your app and are useful when you want to link to a route within your app. This works for both embedded and non-embedded apps.
## shopify:admin
##### Link to Product Page
```tsx
;
```
##### Fetch data
```ts
fetch('shopify:admin/api/graphql.json', {
method: 'POST',
body: JSON.stringify(simpleProductQuery),
});
```
## app:
## Link to Settings
```tsx
;
```
## extension:
## Trigger Action Extension from a Block extension
```tsx
;
```
## /relative/urls
## Link to route in your app
```tsx
;
```
***
## Deploying
Use the Shopify CLI to [deploy your app and its extensions](https://shopify.dev/docs/apps/deployment/extension).
## Deploy an extension
## CLI
```bash
# navigate to your app's root directory:
cd my-app
# deploy your app and its extensions:
npm run deploy
# follow the steps to deploy
```
***
## Security
UI Extensions run on a different origin than the Shopify Admin. For network calls to succeed, your server must support [cross-origin resource sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) for the origin `https://extensions.shopifycdn.com`.
If you have a custom [`Access-Control-Allow-Origin` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin) set, you must include `https://extensions.shopifycdn.com` in the list of allowed origins.
If you are using the [Shopify App Remix Template](https://github.com/Shopify/shopify-app-template-remix), this is done automatically for you.
***
## Tutorials and resources
Deepen your understanding of Admin UI extensions with these tutorials and resources.
[Tutorial - Get started building your first admin extension](#getting-started)
[Component APIs - See all available components](https://shopify.dev/docs/api/admin-extensions/components)
[Reference - View a list of available extension targets](https://shopify.dev/docs/api/admin-extensions/api/extension-targets)
[App authentication - Make authenticated requests to your app's backend](#app-authentication)
[Direct API access - Access the Shopify GraphQL API directly](#direct-api-access)
[Custom protocols - Easily construct URLs to navigate to common locations](#custom-protocols)
[UI reference - Figma UI Kit](https://www.figma.com/community/file/1265417558571498993)
***