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 in real-time. The API enables integration with device cameras, external scanners, and embedded scanning hardware.

Anchor to Use casesUse cases

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

Support

Targets (9)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides barcode and QR code scanning capabilities. Access the following properties on shopify to read scan data, control the camera scanner, and detect available scanner hardware.

Anchor to scannerData scannerData required: Access current scan data and subscribe to new scan events. Use to receive real-time scan results.
Anchor to sources sources required: Access available scanner sources on the device. Use to check which scanners are available (camera, external, or embedded).

ScannerData

Represents the scanner interface for accessing scan events and subscription management. Provides real-time access to scanned data through a reactive signal pattern.

current
Current available scanner sources with subscription support. The `value` property provides current sources, and `subscribe` listens for changes. Use to monitor which scanners are available.
```
ReadonlySignalLike<ScannerSubscriptionResult>
```

ReadonlySignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern.

subscribe
Subscribes to locale changes and calls the provided function whenever the locale updates. Returns an unsubscribe function to clean up the subscription. Use to automatically update your extension content when merchants change their language settings during POS sessions.
```
(fn: (value: T) => void) => () => void
```
value
The current value of the locale string in IETF format. For example, `"en-US"`, `"fr-CA"`, or `"de-DE"`. This property provides immediate access to the current locale without requiring subscription setup. Use for one-time locale checks or initial internationalization setup.
```
T
```

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'` - Built-in device camera used for scanning • `'external'` - External scanner hardware connected to the device • `'embedded'` - Embedded scanner hardware built into the device
```
ScannerSource
```

ScannerSource

The scanner source the POS device supports.

'camera' | 'external' | 'embedded'

ScannerSources

Represents the available scanner hardware sources on the device. Provides reactive access to the list of scanners that can be used for scanning operations.

current
Current available scanner sources with subscription support. The `value` property provides current sources, and `subscribe` listens for changes. Use to monitor which scanners are available.
```
ReadonlySignalLike<ScannerSource[]>
```

Examples

jsx

import {render} from 'preact';

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

export default async () => {

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

};

const Extension = () => {

const [scanData, setScanData] = useState('');

const [scanSource, setScanSource] = useState('');

const [hasCameraScanner, setHasCameraScanner] = useState(false);

const [hasExternalScanner, setHasExternalScanner] = useState(false);

useEffect(() => {

const unsubscribeData = shopify.scanner.scannerData.current.subscribe((result) => {

setScanData(result.data || '');

setScanSource(result.source || '');

});

const unsubscribeSources = shopify.scanner.sources.current.subscribe((sources) => {

setHasCameraScanner(sources.includes('camera'));

setHasExternalScanner(sources.includes('external'));

});

return () => {

unsubscribeData();

unsubscribeSources();

};

}, []);

return (

<s-page heading="Scanner Example">

<s-stack direction="block">

<s-text>Scanned data: {scanData}</s-text>

<s-text>Scanned data source: {scanSource}</s-text>

{hasCameraScanner && (

<s-text>Camera scanner is available</s-text>

)}

{hasExternalScanner && (

<s-text>External scanner is available</s-text>

)}

</s-stack>

</s-page>

);

};

Examples

Description

Subscribe to scan events and adapt behavior based on the scanner source. This example shows how to use `shopify.scanner.subscribe()` to receive scan events and check `shopify.scanner.source` to determine which scanner type was used (camera, external scanner, or embedded hardware). By identifying the scanner type, you can customize handling based on the scanning method.

jsx

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

export default async () => {
  render(<Extension />, document.body);
};

const Extension = () => {
  const [scanData, setScanData] = useState('');
  const [scanSource, setScanSource] = useState('');
  const [hasCameraScanner, setHasCameraScanner] = useState(false);
  const [hasExternalScanner, setHasExternalScanner] = useState(false);

  useEffect(() => {
    const unsubscribeData = shopify.scanner.scannerData.current.subscribe((result) => {
      setScanData(result.data || '');
      setScanSource(result.source || '');
    });

    const unsubscribeSources = shopify.scanner.sources.current.subscribe((sources) => {
      setHasCameraScanner(sources.includes('camera'));
      setHasExternalScanner(sources.includes('external'));
    });

    return () => {
      unsubscribeData();
      unsubscribeSources();
    };
  }, []);

  return (
    <s-page heading="Scanner Example">
      <s-stack direction="block">
        <s-text>Scanned data: {scanData}</s-text>
        <s-text>Scanned data source: {scanSource}</s-text>
        {hasCameraScanner && (
          <s-text>Camera scanner is available</s-text>
        )}
        {hasExternalScanner && (
          <s-text>External scanner is available</s-text>
        )}
      </s-stack>
    </s-page>
  );
};

Description

Subscribe to real-time scan events and maintain a history of scanned items. This example demonstrates using `shopify.scanner.scannerData.current.subscribe()` to capture scan data, source information, and timestamps. Use this pattern for scan logging, bulk scanning workflows, or scan history review.

jsx

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

export default async () => {
  render(<Extension />, document.body);
};

const Extension = () => {
  const [scanData, setScanData] = useState('');
  const [scanSource, setScanSource] = useState('');
  const [scanHistory, setScanHistory] = useState([]);

  useEffect(() => {
    const unsubscribe = shopify.scanner.scannerData.current.subscribe(
      (result) => {
        if (result.data) {
          setScanData(result.data);
          setScanSource(result.source || 'unknown');
          setScanHistory((prev) => [
            {
              data: result.data,
              source: result.source,
              timestamp: new Date().toLocaleTimeString(),
            },
            ...prev,
          ]);
        }
      },
    );

    return () => {
      unsubscribe();
    };
  }, []);

  return (
    <s-page heading="Scanner Data">
      <s-scroll-box>
        <s-stack direction="block">
          <s-section heading="Latest Scan">
            {scanData ? (
              <>
                <s-text>Data: {scanData}</s-text>
                <s-text>Source: {scanSource}</s-text>
              </>
            ) : (
              <s-text>Waiting for scan...</s-text>
            )}
          </s-section>
          {scanHistory.length > 0 && (
            <s-section heading="Recent Scans">
              {scanHistory.map((scan, index) => (
                <s-text key={index}>
                  [{scan.timestamp}] {scan.data} ({scan.source})
                </s-text>
              ))}
            </s-section>
          )}
        </s-stack>
      </s-scroll-box>
    </s-page>
  );
};

Anchor to Best practicesBest practices

Handle scan events reactively: Use subscribe methods to process scan events as they occur for immediate feedback.
Validate scanned data: Validate before processing and handle invalid codes, unsupported formats, or errors.
Provide clear feedback: Show success confirmations, error messages, and guidance when scans fail.
Adapt to available sources: Check available scanner sources and provide alternatives when preferred methods aren't available.
Handle scan data processing: Scan data processing is reactive and requires proper subscription management to avoid memory leaks or unexpected behavior when components unmount.

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.

Was this page helpful?