Choose a version:

Scanner API

The Scanner API provides access to barcode and QR code scanning functionality on POS devices, allowing you to subscribe to scan events, monitor available scanner sources, and process scanned data through subscription callbacks. The API enables integration with device cameras, external scanners, and embedded scanning hardware.

Use cases

Barcode scanning: Implement barcode scanning for product lookup or inventory management.
QR scanning: Build QR code scanning features for customer engagement or loyalty programs.
Custom workflows: Create custom scanning workflows that process scan data.
Real-time feedback: Implement real-time scanning feedback with immediate processing.

Support

Targets (6)

Supported targets

Anchor to scannerapiScannerApi

The ScannerApi object provides access to scanning functionality and scanner source information. Access these properties through api.scanner to monitor scan events and available scanner sources.

Anchor to scannerDataSubscribable scannerDataSubscribable RemoteSubscribable<> required: Subscribe to scan events to receive barcode and QR code data when scanned. Supports one subscription at a time. Use for receiving real-time scan results.
Anchor to scannerSourcesSubscribable scannerSourcesSubscribable RemoteSubscribable<[]> required: Subscribe to changes in available scanner sources on the device. Supports one subscription at a time. Use to monitor which scanners are available (camera, external, or embedded).

ScannerSubscriptionResult

Represents the data from a scanner event. Contains the scanned string data and the hardware source that captured the scan.

data
The string data from the last scanner event received. Contains the scanned barcode, QR code, or other scannable data. Returns `undefined` when no scan data is available. Use to process scanned content and implement scan-based business logic.
```
string
```
source
The scanning source from which the scan event came. Returns one of the following scanner types: - `'camera'` - Device camera for scanning through the camera interface (available on most mobile POS devices) - `'external'` - External scanner hardware connected using USB, Bluetooth, or other methods (handheld scanners, dedicated devices) - `'embedded'` - Built-in scanning hardware integrated into the POS device (specialized terminals with integrated scanning) Returns `undefined` when no scan source is available. Use to implement source-specific logic or provide feedback about scanning method.
```
ScannerSource
```

export interface ScannerSubscriptionResult {
  /**
   * The string data from the last scanner event received. Contains the scanned barcode, QR code, or other scannable data. Returns `undefined` when no scan data is available. Use to process scanned content and implement scan-based business logic.
   */
  data?: string;
  /**
   * The scanning source from which the scan event came. Returns one of the following scanner types:
   *
   * - `'camera'` - Device camera for scanning through the camera interface (available on most mobile POS devices)
   * - `'external'` - External scanner hardware connected using USB, Bluetooth, or other methods (handheld scanners, dedicated devices)
   * - `'embedded'` - Built-in scanning hardware integrated into the POS device (specialized terminals with integrated scanning)
   *
   * Returns `undefined` when no scan source is available. Use to implement source-specific logic or provide feedback about scanning method.
   */
  source?: ScannerSource;
}

ScannerSource

The scanner source the POS device supports.

'camera' | 'external' | 'embedded'

Examples

import React from 'react';

import {

CameraScanner,

Navigator,

Screen,

Stack,

Text,

useScannerDataSubscription,

useScannerSourcesSubscription,

reactExtension,

} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {

const {data, source} = useScannerDataSubscription();

const availableScanners = useScannerSourcesSubscription();

const hasCameraScanner = availableScanners.includes('camera');

return (

{hasCameraScanner ? (

) : (

<Text>{`Scanned data: ${data || ''}`}</Text>

<Text>{`Scanned data source: ${source || ''}`}</Text>

</Stack>

)}

</Stack>

</Screen>

</Navigator>

);

};

export default reactExtension('pos.home.modal.render', () => (

));

Examples

Adapt UI to available scanner types

Description

Adapt your scanning interface based on available hardware capabilities. This example shows how to conditionally render appropriate scanning UI for different device types—using camera scanning on devices with cameras while falling back to embedded scanning on devices like POS GO that lack camera hardware, ensuring a functional experience across all POS devices.

React

import React from 'react';
import {
  CameraScanner,
  Navigator,
  Screen,
  Stack,
  Text,
  useScannerDataSubscription,
  useScannerSourcesSubscription,
  reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {
  const {data, source} = useScannerDataSubscription();
  const availableScanners = useScannerSourcesSubscription();
  const hasCameraScanner = availableScanners.includes('camera');

  return (
    <Navigator>
      <Screen name="Home" title="Home">
        <Stack direction="horizontal">
          {hasCameraScanner ? (
            <CameraScanner />
          ) : (
            <Stack direction="vertical" alignment="space-evenly">
              <Text>{`Scanned data: ${data || ''}`}</Text>
              <Text>{`Scanned data source: ${source || ''}`}</Text>
            </Stack>
          )}
        </Stack>
      </Screen>
    </Navigator>
  );
};

export default reactExtension('pos.home.modal.render', () => (
  <SmartGridModal />
));

TS

import {
  CameraScanner,
  Navigator,
  Screen,
  Stack,
  Text,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.modal.render', (root, api) => {
  const dataText = root.createComponent('Text', null, 'Scanned data: ');

  const sourceText = root.createComponent(
    'Text',
    null,
    'Scanned data source: ',
  );

  const cameraScanner = root.createComponent(CameraScanner);
  const stack1 = root.createComponent(Stack, {
    direction: 'horizontal',
  });
  const stack2 = root.createComponent(Stack, {
    direction: 'vertical',
    alignment: 'space-evenly',
  });

  const screen = root.createComponent(Screen, {
    title: 'Home',
    name: 'Home',
  });

  const navigator = root.createComponent(Navigator);

  screen.append(stack1);
  navigator.append(screen);
  root.append(navigator);

  api.scanner.scannerDataSubscribable.subscribe((data, source) => {
    dataText.replaceChildren(`Scanned data: ${data || ''}`);
    sourceText.replaceChildren(`Scanned data source: ${source || ''}`);
  });

  api.scanner.scannerSourcesSubscribable.subscribe((sources) => {
    // Clear previous children to avoid duplicate appending
    stack1.children = [];
    stack2.children = [];

    if (sources.include('camera')) {
      stack1.append(cameraScanner);
    } else {
      stack2.append(dataText);
      stack2.append(sourceText);
      stack1.append(stack2);
    }
  });
});

Add products from hardware scanner

Description

Automatically add products to the cart when barcodes are scanned using external hardware scanners. This example listens for scan events and uses the scanned data to search for and add matching products, creating a seamless scanning workflow that works with physical scanners connected to the POS device.

React

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

const SmartGridModal = () => {
  const api = useApi<'pos.home.modal.render'>();
  const {data} = useScannerDataSubscription();

  return (
    <Navigator>
      <Screen name="Home" title="Home">
        <Stack direction="horizontal">
          <Text>{`Scanned data: ${data || ''}`}</Text>
        </Stack>
      </Screen>
    </Navigator>
  );
};

export default reactExtension('pos.home.modal.render', () => (
  <SmartGridModal />
));

TS

import React from 'react';
import {
  Navigator,
  Screen,
  Stack,
  Text,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.modal.render', (root, api) => {
  const text = root.createComponent('Text', null, 'Scanned data: ');

  const stack = root.createComponent(Stack, {
    direction: 'horizontal',
  });

  const screen = root.createComponent(Screen, {
    title: 'Home',
    name: 'Home',
  });

  const navigator = root.createComponent(Navigator);

  stack.append(text);
  screen.append(stack);
  navigator.append(screen);
  root.append(navigator);

  api.scanner.scannerDataSubscribable.subscribe((data) => {
    text.replaceChildren(`Scanned data: ${data || ''}`);
  });
});

Monitor available scanner hardware

Description

Subscribe to scanner source changes to detect which scanning methods are available on the device. This example demonstrates tracking available scanner sources (camera, external, embedded) in real time, allowing you to adapt your UI and functionality based on hardware capabilities.

React

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

const SmartGridModal = () => {
  const scannerSources = useScannerSourcesSubscription();

  return (
    <Navigator>
      <Screen name="Home" title="Home">
        <Stack direction="horizontal">
          <Text>{`Available scanner sources: ${scannerSources}`}</Text>
        </Stack>
      </Screen>
    </Navigator>
  );
};

export default reactExtension('pos.home.modal.render', () => (
  <SmartGridModal />
));

TS

import {
  Navigator,
  Screen,
  Stack,
  Text,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.modal.render', (root, api) => {
  const scannerSourcesText = root.createComponent(
    'Text',
    null,
    'Available scanner sources: ',
  );

  const stack1 = root.createComponent(Stack, {
    direction: 'horizontal',
  });

  const screen = root.createComponent(Screen, {
    title: 'Home',
    name: 'Home',
  });

  const navigator = root.createComponent(Navigator);

  stack1.append(scannerSourcesText);
  screen.append(stack1);
  navigator.append(screen);
  root.append(navigator);

  api.scanner.scannerSourcesSubscribable.subscribe((sources) => {
    scannerSourcesText.replaceChildren(`Available scanner sources: ${sources}`);
  });
});

Subscribe to scan events

Description

Subscribe to scan events to process barcode and QR code data as it arrives. This example shows how to listen for scans from any available scanner source (camera, external scanner, or embedded hardware), enabling you to add products to cart, look up information, or trigger custom workflows based on scanned codes.

React

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

const SmartGridModal = () => {
  const {data, source} = useScannerDataSubscription();

  return (
    <Navigator>
      <Screen name="Home" title="Home">
        <Stack direction="horizontal">
          <Text>{`Scanned data: ${data || ''} with ${source || ''}`}</Text>
        </Stack>
      </Screen>
    </Navigator>
  );
};

export default reactExtension('pos.home.modal.render', () => (
  <SmartGridModal />
));

TS

import {
  Navigator,
  Screen,
  Stack,
  Text,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.modal.render', (root, api) => {
  const dataText = root.createComponent('Text', null, 'Scanned data: ');

  const sourceText = root.createComponent(
    'Text',
    null,
    'Scanned data source: ',
  );

  const stack1 = root.createComponent(Stack, {
    direction: 'horizontal',
  });

  const screen = root.createComponent(Screen, {
    title: 'Home',
    name: 'Home',
  });

  const navigator = root.createComponent(Navigator);

  stack1.append(dataText);
  stack1.append(sourceText);
  screen.append(stack1);
  navigator.append(screen);
  root.append(navigator);

  api.scanner.scannerDataSubscribable.subscribe((data, source) => {
    dataText.replaceChildren(`Scanned data: ${data || ''}`);
    sourceText.updateProps(`Scanned data source: ${source || ''}`);
  });
});

Anchor to best-practicesBest practices

Manage subscriptions carefully: Remember that RemoteSubscribable supports only one subscription at a time. If you need multiple subscriptions, use makeStatefulSubscribable or manage subscription cleanup to avoid conflicts.
Validate scanned data appropriately: Validate scanned data before processing, implementing proper error handling for invalid codes, unsupported formats, or scanning errors.
Provide clear scanning feedback: Give users clear feedback about scan results, including success confirmations, error messages, and guidance when scans fail or produce invalid data.
Adapt to available scanner sources: Check available scanner sources and adapt your interface accordingly.

Anchor to limitationsLimitations

The Scanner API is only available in action (modal) targets where scanning functionality is supported and can't be used in other targets.
RemoteSubscribable supports only one subscription at a time. Use makeStatefulSubscribable if you need multiple components to subscribe to scan events simultaneously.
Scanning availability depends on device hardware capabilities and may vary between different POS devices and configurations.

Was this page helpful?