Admin UI extensions

Admin UI extensions make it possible to surface contextual app functionality within the Shopify Admin interface.

Choose a version:

Anchor to Getting startedGetting started

Use the Shopify CLI to generate a new extension within your app.

If you already have a Shopify app, you can skip right to the last command shown here.

Anchor to App authenticationApp 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. 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

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, () => <App />);

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 <Text>Info: {productInfo?.title}</Text>;

}

Anchor to Direct API accessDirect API access

You can make Shopify Admin API requests directly from your extension using the query API or the standard web fetch API!

Any fetch() calls to Shopify's Admin GraphQL API from your extension are automatically authenticated by default. They're fast too, since requests are handled directly by Shopify.

Direct API requests use Online access mode. This means Direct API calls are restricted to the scopes available to the user that's using the extension. If your extension needs to use the offline access mode, you should make requests using your app's backend.

Developer guideLearn more about access scopes

Query Shopify data

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, () => <App />);

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 <Text strong>The selected product title is {product?.title}</Text>;

}

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, () => <App />);

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 <Text strong>The selected product title is {product?.title}</Text>;

}

Fetch Product data

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, () => <App />);

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 <Text strong>The selected product title is {product?.title}</Text>;
}

Query Product data

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, () => <App />);

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 <Text strong>The selected product title is {product?.title}</Text>;
}

Anchor to Custom protocolsCustom 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="shopify:admin/products/1234567890" />;

fetch('shopify:admin/api/graphql.json', {

method: 'POST',

body: JSON.stringify(simpleProductQuery),

});

Anchor to DeployingDeploying

Use the Shopify CLI to deploy your app and its extensions.

Anchor to Tutorials and resourcesTutorials and resources

Deepen your understanding of Admin UI extensions with these tutorials and resources.

TutorialGet started building your first admin extension

Component APIsSee all available components

ReferenceView a list of available extension targets

App authenticationMake authenticated requests to your app's backend

Direct API accessAccess the Shopify GraphQL API directly

Custom protocolsEasily construct URLs to navigate to common locations

UI referenceFigma UI Kit

Was this page helpful?