POS UI extensions

Build extensions that integrate into Shopify's Point of Sale 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.

Choose a version:

Anchor to Getting startedGetting started

POS UI extensions require a TOML configuration file and TSX (or JSX) files containing your Preact-based extension code.

Use 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.

If your app uses ESLint, update your configuration to include the global shopify object to prevent linting errors.

TutorialGetting started with POS UI extensions

Anchor to Building your extensionBuilding 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 Polaris web components that define which interface elements you can use.

Anchor to Targets: Choose where your extension appearsTargets: Choose where your extension appears

Targets define where your extensions appear within Shopify's POS interface and what capabilities they have. There are three 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.

ReferenceExplore all targets

Anchor to Target APIs: Define what your extension doesTarget 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.

ReferenceExplore all target APIs

Anchor to Polaris web components: Design your interfacePolaris web components: Design your interface

Polaris web components are the UI building blocks that you use to display data and trigger API functions. These components are native UI elements that follow Shopify's design system and are built with remote-dom, Shopify's library for building cross-platform user interfaces.

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

ReferenceExplore all Polaris web components

Anchor to ConfigurationConfiguration

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.

Anchor to PropertiesProperties

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.
name: required The merchant-facing name of the extension. After you generate an 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.
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.

[[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.

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

Anchor to Direct API accessDirect 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 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 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

import {render} from 'preact';

import {useState, useEffect} from 'preact/hooks';

// This mutation requires the `write_products` access scope.

// /docs/api/admin-graphql/latest/mutations/metafieldsset

async function mutateMetafield(productId) {

const requestBody = {

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',

type: 'single_line_text_field',

};

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

method: 'POST',

body: JSON.stringify(requestBody),

});

}

// This query requires the `read_products` access scope.

// /docs/api/admin-graphql/latest/queries/product

async function queryProductMetafields(productId) {

const requestBody = {

query: `#graphql

query GetProduct($id: ID!) {

product(id: $id) {

metafields(first: 10) {

edges {

node {

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 async () => {

render(<ProductDetailsBlock />, document.body);

};

export function ProductDetailsBlock() {

const [productInfo, setProductInfo] = useState('');

useEffect(() => {

async function getProductInfo() {

const result = await queryProductMetafields(shopify.product.id);

setProductInfo(JSON.stringify(result, null, 2));

}

getProductInfo();

}, [shopify.product.id]);

return (

<s-pos-block>

<s-box padding="large">

<s-text>Metafields: {productInfo}</s-text>

</s-box>

<s-box padding="large">

<s-text>Set Metafields: {productInfo}</s-text>

<s-button onClick={() => mutateMetafield(shopify.product.id)}>Set Metafields</s-button>

</s-box>

</s-pos-block>

);

}

Anchor to Testing and deploymentTesting and deployment

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

Testing POS UI extensions requires a development store and the Shopify POS app on any mobile or tablet device—no dedicated POS hardware needed. Download the POS app from the App Store or Google Play, 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 to deploy your app and its extensions to production.