Complete Guide: How to Implement Shopify POS UI Extensions
#shopifyposextensions#shopifydevelopment#posuiintegration#shopifyappdevelopment
Tirth Godhani

Tirth Godhani @tirth_godhani

About: Senior Software Engineer with 4 years’ experience in MEAN/MERN stacks. Holds an MCA from Gujarat Technological University & Veer Narmad South Gujarat University.

Joined:
Jul 15, 2025

Complete Guide: How to Implement Shopify POS UI Extensions

Publish Date: Jul 15
11 3

Introduction

Shopify POS UI Extensions are powerful tools that allow developers to integrate custom functionality directly into the Shopify Point of Sale interface. Whether you're building inventory management tools, customer loyalty systems, or custom checkout flows, POS extensions provide a seamless way to enhance the in-store experience.

In this comprehensive guide, we'll walk through the entire process of creating and deploying a POS UI extension from scratch. By the end, you'll have a fully functional extension that you can customize for your specific business needs.

What Are POS UI Extensions?

POS UI extensions are React-based components that integrate seamlessly into the Shopify POS interface. They provide several key capabilities:

  • Home Screen Tiles: Display custom tiles on the POS home screen for quick access
  • Modal Dialogs: Present complex interfaces in modal windows
  • Session Access: Retrieve staff information and store context
  • API Integration: Communicate with your backend services
  • Real-time Updates: Provide live functionality for store operations

These extensions run within the POS environment, giving store staff access to your app's features without leaving the POS interface.

Prerequisites

Before we begin, ensure you have the following:

Required Tools

  • Shopify Partner Account: Access to create and manage apps
  • Shopify CLI: Latest version installed
  • Node.js: Version 16 or higher
  • Existing Shopify App: App with proper configuration
  • POS Access: Store with POS enabled

Required Permissions

Your app needs these scopes in your shopify.app.toml:

[access_scopes]
scopes = "read_customer_events,read_customers,read_locations,read_payment_terms,read_shipping,write_customers,write_discounts,write_draft_orders,write_gift_cards,write_inventory,write_orders,write_price_rules,write_products,write_publications,write_returns,write_shipping,write_gift_card_transactions,read_gift_cards,read_gift_card_transactions,read_products"
Enter fullscreen mode Exit fullscreen mode

Step 1: Environment Setup

Install Shopify CLI

First, install the Shopify CLI globally:

npm install -g @shopify/cli @shopify/theme
Enter fullscreen mode Exit fullscreen mode

Verify the installation:

shopify version
Enter fullscreen mode Exit fullscreen mode

Login to Shopify

Authenticate with your Shopify Partner account:

shopify auth login
Enter fullscreen mode Exit fullscreen mode

Verify your login status:

shopify auth list
Enter fullscreen mode Exit fullscreen mode

Navigate to Your App 

cd your-shopify-app
ls
# Should see files like: shopify.app.toml, package.json, etc.
Enter fullscreen mode Exit fullscreen mode

Step 2: Generate the Extension

Create the Extension

Generate a new POS UI extension using the Shopify CLI:

shopify app generate extension
Enter fullscreen mode Exit fullscreen mode

Follow the interactive prompts:

  1. Select "UI Extension"
  2. Choose "Point of Sale"
  3. Enter your extension name (e.g., "my-pos-extension")
  4. Wait for the generation to complete

Navigate and Install Dependencies 

cd extensions/your-pos-extension
npm install
ls -la
Enter fullscreen mode Exit fullscreen mode

Step 3: Configure POS Settings in Partner Account

Enable POS Integration

Before your extension can work in POS, you need to configure the POS settings in your Shopify Partner account:

  1. Navigate to Partner Account:

  2. Access Your App:

    • Click on "Apps" in the left sidebar
    • Select "All apps"
    • Find and click on your app name

  3. Configure POS Settings:

    • In the left sidebar, under "Build", click on "Configuration"
    • Scroll down to the "POS" section
    • Find the setting "Embed app in Shopify POS"
    • Toggle to "True" (this is crucial for POS extensions to work)

Note: This setting must be enabled for your POS extension to appear in the Shopify POS interface.

Update Extension Configuration

Edit the shopify.extension.toml file:

api_version = "2025-04"

[[extensions]]
type = "ui_extension"
name = "your-pos-extension"
handle = "your-pos-extension"
description = "Your custom POS functionality"

# Tile on home screen
[[extensions.targeting]]
module = "./src/Tile.jsx"
target = "pos.home.tile.render"

# Modal dialog
[[extensions.targeting]]
module = "./src/Modal.jsx"
target = "pos.home.modal.render"
Enter fullscreen mode Exit fullscreen mode

Update Package Dependencies

Ensure your package.json has the correct dependencies:

{
  "name": "your-pos-extension",
  "private": true,
  "version": "1.0.0",
  "dependencies": {
    "react": "^18.0.0",
    "@shopify/ui-extensions": "2025.4.x",
    "@shopify/ui-extensions-react": "2025.4.x",
    "react-reconciler": "0.29.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 4: Create Basic Components

Create the Tile Component

The tile component appears on the POS home screen. Create src/Tile.jsx:

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

const TileComponent = () => {
  const api = useApi();

  return (
    <Tile
      title="Your App Name"
      subtitle="Quick actions"
      onPress={() => {
        api.action.presentModal();
      }}
      enabled
    />
  );
};

export default reactExtension('pos.home.tile.render', () => <TileComponent />);
Enter fullscreen mode Exit fullscreen mode

Create the Modal Component

The modal provides the main interface. Create src/Modal.jsx:

import React, { useState, useEffect } from 'react';
import {
  reactExtension,
  Screen,
  Stack,
  Text,
  useApi,
} from '@shopify/ui-extensions-react/point-of-sale';

const Modal = () => {
  const [data, setData] = useState(null);
  const api = useApi();
  const staff = api.session?.staff;

  useEffect(() => {
    const initialize = async () => {
      try {
        const sessionToken = await api.session.getSessionToken();
        console.log('Session token obtained');
        // Your initialization logic here
      } catch (error) {
        console.error('Failed to get session token:', error);
      }
    };

    initialize();
  }, [api]);

  return (
    <Screen name="YourApp" title="Your App Title">
      <Stack direction="vertical" padding="large" fill>
        <Text>Welcome, {staff?.firstName || 'Staff Member'}!</Text>
        <Text>Your custom POS extension is working!</Text>
      </Stack>
    </Screen>
  );
};

export default reactExtension('pos.home.modal.render', () => <Modal />);
Enter fullscreen mode Exit fullscreen mode

Step 5: Set Up API Integration

Create API Service

Create src/services/apiService.js for handling API calls:

import { API_ENDPOINTS } from '../constants/api';

export const apiService = {
  async makeRequest(endpoint, data, sessionToken) {
    try {
      const response = await fetch(endpoint, {
        method: 'POST',
        headers: { 
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${sessionToken}`
        },
        body: JSON.stringify(data),
      });

      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }

      return response.json();
    } catch (error) {
      console.error('API request failed:', error);
      throw error;
    }
  },

  async createItem(data, sessionToken) {
    return this.makeRequest(API_ENDPOINTS.CREATE_ITEM, data, sessionToken);
  },

  async searchItems(params, sessionToken) {
    return this.makeRequest(API_ENDPOINTS.SEARCH_ITEMS, params, sessionToken);
  },
};
Enter fullscreen mode Exit fullscreen mode

Create API Constants

Create src/constants/api.js for endpoint configuration:

const BASE_URL = process.env.API_URL || 'https://your-backend.com';

export const API_ENDPOINTS = {
  CREATE_ITEM: `${BASE_URL}/api/create-item`,
  SEARCH_ITEMS: `${BASE_URL}/api/search-items`,
  UPDATE_ITEM: `${BASE_URL}/api/update-item`,
  DELETE_ITEM: `${BASE_URL}/api/delete-item`,
};
Enter fullscreen mode Exit fullscreen mode

Step 6: Development and Testing

Start Development Server 

shopify app dev
Enter fullscreen mode Exit fullscreen mode

Test Your Extension

  1. Open Shopify POS
  2. Navigate to your store
  3. Look for your tile on the home screen
  4. Tap the tile to open the modal
  5. Verify all functionality works

Essential Development Commands 

# Check app status
shopify app info

# View app logs
shopify app logs

# Check configuration
shopify app config show

# Link to development store
shopify app config link

# Validate extension
shopify app validate
Enter fullscreen mode Exit fullscreen mode

Step 7: Deployment

Deploy to Development 

# Deploy to development store
shopify app deploy

# Deploy specific extension
shopify app deploy --extensions=your-pos-extension

# Deploy with force (overwrite existing)
shopify app deploy --force
Enter fullscreen mode Exit fullscreen mode

Deploy to Production 

# Deploy to production
shopify app deploy --force

# Deploy with specific environment
shopify app deploy --environment=production

# Deploy with custom configuration
shopify app deploy --config=production.toml
Enter fullscreen mode Exit fullscreen mode

Environment Management 

# List environments
shopify app env list

# Create new environment
shopify app env create

# Switch environment
shopify app env use production

# Delete environment
shopify app env delete
Enter fullscreen mode Exit fullscreen mode

Troubleshooting Common Issues

Extension Not Appearing

First, check POS configuration in Partner account:

  1. Go to partners.shopify.com
  2. Navigate to Apps > All apps > Your App > Configuration
  3. Ensure "Embed app in Shopify POS" is set to "True"
  4. Save the configuration

Then check deployment:

# Check if app is installed
shopify app info

# Verify deployment
shopify app deploy --force

# Check configuration
shopify app config show

# Reinstall app
shopify app config unlink
shopify app config link
Enter fullscreen mode Exit fullscreen mode

Development Server Issues 

# Reset development environment
shopify app dev --reset

# Clear cache
shopify app dev --clear-cache

# Check for port conflicts
shopify app dev --port=3001
Enter fullscreen mode Exit fullscreen mode

API Call Failures 

# Check network connectivity
curl -I https://your-backend.com

# Verify CORS settings
# Check browser console for errors

# Test API endpoints manually
curl -X POST https://your-backend.com/api/test
Enter fullscreen mode Exit fullscreen mode

Debug Commands 

# Check extension status
shopify app info --extensions

# View deployment logs
shopify app logs --follow

# Validate extension configuration
shopify app validate

# Check for syntax errors
npm run lint

# Test extension locally
shopify app dev --tunnel
Enter fullscreen mode Exit fullscreen mode

Conclusion

Implementing a Shopify POS UI Extension opens up powerful possibilities for enhancing the in-store experience. By following this guide, you've learned how to:

  • Set up the development environment
  • Generate and configure extensions
  • Create React-based components
  • Integrate with backend APIs
  • Deploy and test your extension
  • Troubleshoot common issues

Remember to start simple and iterate, test thoroughly in real POS environments, and follow Shopify's design and development guidelines. With practice, you'll be able to create sophisticated POS extensions that significantly enhance store operations.

For additional resources and advanced topics, refer to the Shopify POS UI Extensions documentation.

Happy coding! 🚀

Comments 3 total

  • Bhautik Domadiya
    Bhautik DomadiyaJul 15, 2025

    👌🏻

  • Simon Hobbs
    Simon HobbsJul 19, 2025

    shopify auth login doesn't exist in 3.82.1

    • Tirth Godhani
      Tirth GodhaniJul 30, 2025

      Yes, you can try running shopify auth logout first. Then run shopify app — it will automatically give you a login link to sign in to your account.

Add comment