---
title: POS UI extensions
description: |
  Build extensions that integrate into Shopify's Point of Sale interface.
api_version: 2025-07
api_name: pos-ui-extensions
source_url:
  html: 'https://shopify.dev/docs/api/pos-ui-extensions/2025-07'
  md: 'https://shopify.dev/docs/api/pos-ui-extensions/2025-07.md'
---

# POS UI extensions

Build extensions that integrate into [Shopify's Point of Sale](https://shopify.dev/docs/apps/build/pos) interface. For example, you can add a clickable tile to the POS home screen that launches your app's features, insert custom content sections into checkout and sales processes, or show additional product details.

Extensions run in the context of key merchant workflows, so always prioritize performance.

## Getting started

POS UI extensions require a set of essential files, including a TOML configuration file and JavaScript or TypeScript modules containing your extension code.

Use [Shopify CLI](https://shopify.dev/docs/api/shopify-cli) to scaffold your extension with the essential configuration and files. You can alter the default configuration later to customize the way your POS UI extension operates.

## Generate scaffold

```terminal
cd my-app
shopify app generate extension
```

[Tutorial - Getting started with POS UI extensions](https://shopify.dev/docs/apps/build/pos/getting-started)

***

## Building your extension

POS UI extensions are made up of three interconnected parts: **targets** that determine where your extension appears in the POS interface, **target APIs** that provide access to data and functionality based on your chosen target, and **UI components** that define which interface elements you can use.

### Targets: Choose where your extension appears

Targets define where your extensions appear within Shopify's POS interface and what capabilities they have. There are four types of targets:

| Target type | Description |
| - | - |
| Tile | Appear on the smart grid (homepage) of the POS system. Use to show status, quickly access common actions, and initiate workflows. |
| Action | Trigger workflows and display modals. This target has two varieties, commonly used together: - **Menu item:** Add buttons to action menus on native POS screens. Use to provide entry points that launch modals.
- **Modal:** Display full-screen interfaces for complete workflows, forms, or multi-step processes. Modals are launched from tiles or menu items. |
| Block | Appear as inline content within native POS screens. Use to render content such as metrics, instructions, or printed content on receipts. |
| Event | Observe transaction events in the background without displaying UI. Use to respond to merchant actions, sync data, or collect analytics. |

[Reference - Explore all targets](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets)

![Placeholder image](https://shopify.dev/images/templated-apis-screenshots/pos-ui-extensions/2025-07/pos-overview-targets.png)

### Target APIs: Define what your extension does

Your extension might show customer loyalty points during checkout, add a custom "Print warranty card" action after completing a purchase, or capture additional product details when staff view inventory.

Use Target APIs to access the data and functionality you need for each scenario—Customer API for loyalty points, Session API for transaction details, or Storage API for capturing custom information.

[Reference - Explore all target APIs](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/target-apis)

## Storage API: Getting a single value

##### React

```typescript
import React from 'react';
import {
  Tile,
  reactExtension,
  useApi,
} from '@shopify/ui-extensions-react/point-of-sale';

const TileComponent = () => {
  const api = useApi<'pos.home.tile.render'>();
  return (
    <Tile
      title="Storage app"
      subtitle="Get example"
      onPress={async () => {
        const storedData = await api.storage.get('key');
        api.toast.show(String(storedData ?? ''));
      }}
      enabled
    />
  );
};

export default reactExtension('pos.home.tile.render', () => <TileComponent />);
```

##### TypeScript

```typescript
import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'Storage app',
    subtitle: 'Get example',
    enabled: `true`,
    onPress: async () => {
      const storedData = await api.storage.get('key');
      api.toast.show(String(storedData ?? ''));
    },
  });

  root.append(tile);
});
```

### UI components: Design your interface

UI components are the building blocks that you use to display data and trigger API functions in POS UI extensions. These components follow [Shopify's design system](https://shopify.dev/docs/apps/design) and render optimized interfaces for retail workflows in [the POS app](https://apps.shopify.com/shopify-pos) on iOS and Android devices.

Components are available as React components or JavaScript objects, imported from `@shopify/ui-extensions/point-of-sale`. The components are built with [remote-ui](https://github.com/Shopify/remote-dom), Shopify's library for building cross-platform user interfaces.

Use UI components to build interfaces that automatically adapt across iOS and Android devices running Shopify POS.

[Reference - Explore all UI components](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/ui-components)

## Tile component: Render a tile on the smart grid

##### React

```typescript
import React from 'react'
import { Tile, reactExtension, useApi } from '@shopify/ui-extensions-react/point-of-sale'

const TileComponent = () => {
  const api = useApi()
  return (
    <Tile
      title="My app"
      subtitle="Hello world!"
      onPress={() => {
        api.action.presentModal()
      }}
      enabled
    />
  )
}

export default reactExtension('pos.home.tile.render', () => {
  return <TileComponent />
})
```

##### TypeScript

```typescript
import {
  Tile,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension(
'pos.home.tile.render',
(root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My app',
    subtitle: 'Hello world!',
    enabled: `true`,
    onPress: () => {
      api.action.presentModal();
    },
  });

  root.append(tile);
  },
);
```

![Placeholder image](https://shopify.dev/images/templated-apis-screenshots/pos-ui-extensions/2025-07/tile-default.png)

***

## Configuration

POS UI extensions rely on a `shopify.extension.toml` file that contains the extension's configuration. This includes the extension name, type, API version, and targeting definitions.

The `name` value is what displays in the POS interface to merchants, so consider this value carefully. We recommend that the `api_version` reflects the latest supported API version.

### Properties

POS UI extensions use the following configuration properties:

##### `api_version` required

The version of the API that's being used for the extension. If provided in the `[[extensions]]` array, then the specified API version is used instead of the root level `api_version`.

##### `[[extensions]]` required

The name of the array that contains all extensions listed in the TOML file. Contains the following properties:

* `type`: required The extension type. For more information, refer to [Extension types](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#extension-types).

* `name`: required The merchant-facing name of the extension. After you [generate an extension](https://shopify.dev/docs/api/shopify-cli/app/app-generate-extension), you're prompted to provide a name for your extension. The `name` property is translatable if it starts with a `t:` and uses a key defined in your translation data. For example, you might have a `t:name` key that matches a translation key called `name`. [Learn more about localization](https://shopify.dev/docs/apps/build/checkout/localized-checkout-ui-extensions#how-it-works).

* `handle`: required The unique internal identifier for the extension. After you create a draft version of the extension, or deploy an extension, you can't change the `handle` value. If not specified, the `handle` value is automatically populated using a transformed `name` value that removes any unsupported characters. For example, if you enter `google maps` as the extension name, then Shopify populates the `handle` value as `google-maps`.

* `description`: required The merchant-facing description of the extension. The `description` property is translatable if it starts with a `t:` and uses a key defined in your translation data. For example, `t:description` and you have a matching translation key called `description`. [Learn more about localization](https://shopify.dev/docs/apps/build/checkout/localized-checkout-ui-extensions#how-it-works).

##### `[[extensions.targeting]]` required

The name of the array that contains a target and its associated module. Contains the following properties:

* `target`: required

  An identifier that specifies where you're injecting your extension into the POS interface.

* `module`: required

  The path to the JavaScript or TypeScript file that contains your extension code. This file exports the extension function that renders your UI or handles events.

## shopify.extension.toml

```toml
api_version = "2025-07"


[[extensions]]
type = "ui_extension"
name = "My POS UI extension"
handle = "my-pos-ui-extension"
description = "My POS UI extension description"


    [[extensions.targeting]]
    target = "pos.home.tile.render"
    module = "./src/Tile.tsx"


    [[extensions.targeting]]
    target = "pos.home.modal.render"
    module = "./src/Modal.tsx"
```

***

## App authentication

Use authenticated requests when your extension needs to fetch data or trigger actions on your own backend service. For example, you might need to display a customer's loyalty status, process a custom discount calculation, or log POS transactions to an external analytics system.

Extensions automatically include authorization headers when making requests to your app's domain. Relative URLs resolve against your `app_url`.

Note

App authentication is available as of POS version 10.6.0 for extensions targeting 2025-07 or later.

ID tokens are only returned for authenticated users with proper app permissions. Without correct permissions, the token will be `null`. POS Staff members aren't authenticated users. [Learn more about configuring app permissions](https://help.shopify.com/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions).

## Make requests to your app's backend

##### React

```typescript
import {
reactExtension,
useApi,
Text,
POSBlock,
POSBlockRow,
} from '@shopify/ui-extensions-react/point-of-sale';
import {useEffect, useState} from 'react';

const CustomerDetailsBlock = () => {
const {customer} = useApi<'pos.customer-details.block.render'>();
const [loyaltyInfo, setLoyaltyInfo] = useState<any>();
useEffect(() => {
    getLoyaltyInfo();
}, [customer.id]);

async function getLoyaltyInfo() {
    const res = await fetch(`${URL}/api/loyalty/${customer.id}`);
    const json = await res.json();
    setLoyaltyInfo(json.loyaltySummary);
}

return (
    <POSBlock>
    <POSBlockRow>
        <Text>{loyaltyInfo}</Text>
    </POSBlockRow>
    </POSBlock>
);
};

export default reactExtension('pos.customer-details.block.render', () => (
<CustomerDetailsBlock />
));
```

##### TypeScript

```typescript
import {
extension,
POSBlock,
Text,
POSBlockRow,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.customer-details.block.render', (root, api) => {
const customerId = api.customer.id;
const infoText = root.createComponent(Text);
const posBlockRow = root.createComponent(POSBlockRow);

async function getLoyaltyInfo() {
    const res = await fetch(`${URL}/api/loyalty/${customerId}`);
    const json = await res.json();
    infoText.replaceChildren(json.loyaltySummary);
}

posBlockRow.append(infoText);
const posBlock = root.createComponent(POSBlock);

posBlock.append(posBlockRow);
root.append(posBlock);

getLoyaltyInfo();
});
```

***

## Direct API access

Use direct API access when your extension needs to query or modify Shopify data in real-time. For example, you might want to update product metafields based on POS interactions, fetch detailed customer order history, or modify inventory levels during special promotions.

Make [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql) requests directly from your extension with automatic authentication. These requests are fast because Shopify handles them directly without requiring a round trip to your backend.

Note

Direct API access is available as of POS version 10.6.0 for extensions targeting 2025-07 or later.

You must declare all required [access scopes](https://shopify.dev/docs/api/usage/access-scopes) in your app's TOML file. For local development, access scopes are only registered or updated when the app is deployed and installed on your test store.

## Query Shopify data directly

##### React

```typescript
import {
reactExtension,
useApi,
POSBlock,
POSBlockRow,
Text,
} from '@shopify/ui-extensions-react/point-of-sale';
import type {DirectApiRequestBody} from '@shopify/ui-extensions/point-of-sale';
import React, {useEffect, useState} from 'react';

// This mutation requires the `write_products` access scope.
// https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/metafieldsset
async function mutateMetafield(productId: number) {
const requestBody: DirectApiRequestBody = {
    query: `#graphql
        mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {
        metafieldsSet(metafields: $metafields) {
            metafields {
            key
            namespace
            value
            createdAt
            updatedAt
            }
        }
        }
    `,
    variables: {
    metafields: [
        {
        key: 'direct_api',
        namespace: 'custom',
        ownerId: `gid://shopify/Product/${productId}`,
        value: 'Example Value',
        },
    ],
    },
};

await fetch('shopify:admin/api/graphql.json', {
    method: 'POST',
    body: JSON.stringify(requestBody),
});
}

// https://shopify.dev/docs/api/admin-graphql/2025-07/queries/product
async function queryProductMetafields(productId: number) {
const requestBody: DirectApiRequestBody = {
    query: `#graphql
    query GetProduct($id: ID!) {
        product(id: $id) {
        id
        metafields(first: 10) {
            edges {
            node {
                id
                namespace
                key
                value
            }
            }
        }
        }
    }
    `,
    variables: {id: `gid://shopify/Product/${productId}`},
};
const res = await fetch('shopify:admin/api/graphql.json', {
    method: 'POST',
    body: JSON.stringify(requestBody),
});
return res.json();
}

const ProductDetailsBlock = () => {
const {product} = useApi<'pos.product-details.block.render'>();
const [productInfo, setProductInfo] = useState<string>('');
useEffect(() => {
    async function getProductInfo() {
    const result = await queryProductMetafields(product.id);
    setProductInfo(JSON.stringify(result, null, 2));
    }
    getProductInfo();
}, [product.id]);

return (
    <POSBlock>
    <POSBlockRow>
        <Text>Metafields: {productInfo}</Text>
    </POSBlockRow>
    <POSBlockRow onPress={() => mutateMetafield(product.id)}>
        <Text>Set metafield</Text>
    </POSBlockRow>
    </POSBlock>
);
};

export default reactExtension('pos.product-details.block.render', () => (
<ProductDetailsBlock />
));
```

##### TypeScript

```typescript
import {
extension,
POSBlock,
POSBlockRow,
Text,
} from '@shopify/ui-extensions/point-of-sale';
import type {DirectApiRequestBody} from '@shopify/ui-extensions/point-of-sale';

// This mutation requires the `write_products` access scope.
// https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/metafieldsset
async function mutateMetafield(productId: number) {
const requestBody: DirectApiRequestBody = {
    query: `#graphql
        mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {
        metafieldsSet(metafields: $metafields) {
            metafields {
            key
            namespace
            value
            createdAt
            updatedAt
            }
        }
        }
    `,
    variables: {
    metafields: [
        {
        key: 'direct_api',
        namespace: 'custom',
        ownerId: `gid://shopify/Product/${productId}`,
        value: 'Example Value',
        },
    ],
    },
};

await fetch('shopify:admin/api/graphql.json', {
    method: 'POST',
    body: JSON.stringify(requestBody),
});
}

// https://shopify.dev/docs/api/admin-graphql/2025-07/queries/product
async function queryProductMetafields(productId: number) {
const requestBody: DirectApiRequestBody = {
    query: `#graphql
    query GetProduct($id: ID!) {
        product(id: $id) {
        id
        metafields(first: 10) {
            edges {
            node {
                id
                namespace
                key
                value
            }
            }
        }
        }
    }
    `,
    variables: {id: `gid://shopify/Product/${productId}`},
};
const res = await fetch('shopify:admin/api/graphql.json', {
    method: 'POST',
    body: JSON.stringify(requestBody),
});
return res.json();
}

export default extension('pos.product-details.block.render', (root, api) => {
const productId = api.product.id;
const metafieldInfoText = root.createComponent(Text);
const metafieldInfoRow = root.createComponent(POSBlockRow);

const setMetafieldText = root.createComponent(Text);
setMetafieldText.append('Set Metafield');

const setMetafieldRow = root.createComponent(POSBlockRow, {
    onPress: () => mutateMetafield(productId),
});

async function getProductInfo() {
    const result = await queryProductMetafields(productId);
    metafieldInfoText.replaceChildren(JSON.stringify(result, null, 2));
}

metafieldInfoRow.append(metafieldInfoText);
setMetafieldRow.append(setMetafieldText);

const posBlock = root.createComponent(POSBlock);

posBlock.append(metafieldInfoRow);
posBlock.append(setMetafieldRow);
root.append(posBlock);

getProductInfo();
});
```

***

## Testing and deployment

After you've built your extension, test it thoroughly and deploy it to production.

Testing POS UI extensions requires a [development store](https://shopify.dev/docs/api/development-stores) and the [Shopify POS app](https://www.shopify.com/pos/pos-app) on any mobile or tablet device—no dedicated POS hardware needed. Download the POS app from the [App Store](https://apps.apple.com/us/app/shopify-point-of-sale-pos/id686830644) or [Google Play](https://play.google.com/store/apps/details?id=com.shopify.pos\&hl=en_US), log in to your development store, and start testing.

Extensions run in preview mode during development, allowing you to test functionality and iterate quickly without affecting live merchant operations.

Use [Shopify CLI](https://shopify.dev/docs/api/shopify-cli) to deploy your app and its extensions to production.

[Tutorial - Debugging POS UI extensions](https://shopify.dev/docs/apps/build/pos/debugging)

[Tutorial - Troubleshooting POS UI extensions](https://shopify.dev/docs/apps/build/pos/troubleshooting)

## Deploy your extension

```terminal
cd my-app
npm run deploy
```

***

## Tutorials and resources

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

### Tutorials

[Tutorial - Getting started with POS UI extensions](https://shopify.dev/docs/apps/build/pos/getting-started)

[Tutorial - Build a discount extension](https://shopify.dev/docs/apps/build/pos/build-discount-extension)

[Tutorial - Build a print extension](https://shopify.dev/docs/apps/build/pos/build-print-extension)

[Tutorial - Communicate with a server](https://shopify.dev/docs/apps/build/pos/communicate-with-server)

### Community resources

[Reference - Developer changelog for POS UI extensions](https://shopify.dev/changelog?filter=pos-extensions)

[Community - Community forum for POS UI extensions](https://community.shopify.dev/tag/pos-extensions)

***