Choose a version:

Session API

The Session API provides access to current POS session information and secure authentication tokens, allowing you to retrieve shop details, user information, location data, and generate tokens for secure backend communication. The API includes both static session data and dynamic token generation for authenticated API calls.

Use cases

Authentication: Authenticate API calls to your app's backend using secure session tokens.
Shop context: Customize extension behavior based on shop domain or location settings.
Location features: Implement location-specific features like tax calculations or inventory checks.
User tracking: Track user activity and staff member interactions for analytics.

Support

Targets (25)

Supported targets

Anchor to sessionapiSessionApi

The SessionApi object provides access to current session information and authentication methods. Access these properties and methods through api.session to retrieve shop data and generate secure tokens. These methods enable secure API calls while maintaining user privacy and app permissions.

Anchor to currentSession currentSession required: Provides comprehensive information about the current POS session including shop details, user authentication, location data, staff member information, currency settings, and POS version. This data is static for the duration of the session and updates when users switch locations or staff members change.
Anchor to getSessionToken getSessionToken () => Promise<string> required: Generates a fresh session token for secure communication with your app's backend service. Returns undefined when the authenticated user lacks proper app permissions. The token is a Shopify OpenID Connect ID Token that should be used in Authorization headers for backend API calls. This is based on the authenticated user, not the pinned staff member.

Session

Defines information about the current POS session.

currency
The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
```
CurrencyCode
```
locationId
The location ID associated with the POS device's current location.
```
number
```
posVersion
The version of [the POS app](https://apps.shopify.com/shopify-pos) currently running.
```
string
```
shopDomain
The shop domain associated with the shop currently logged into POS.
```
string
```
shopId
The shop ID associated with the shop currently logged into POS.
```
number
```
staffMemberId
The staff ID of the staff member currently pinned into the POS. This may differ from the user ID if the pinned staff member is different from the logged-in user.
```
number
```
userId
The user ID associated with the Shopify account currently authenticated on POS.
```
number
```

export interface Session {
  /**
   * The shop ID associated with the shop currently logged into POS.
   */
  shopId: number;

  /**
   * The user ID associated with the Shopify account currently authenticated on POS.
   */
  userId: number;

  /**
   * The shop domain associated with the shop currently logged into POS.
   */
  shopDomain: string;

  /**
   * The location ID associated with the POS device's current location.
   */
  locationId: number;

  /**
   * The staff ID of the staff member currently pinned into the POS. This may differ from the user ID if the pinned staff member is different from the logged-in user.
   */
  staffMemberId?: number;

  /**
   * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
   */
  currency: CurrencyCode;

  /**
   * The version of [the POS app](https://apps.shopify.com/shopify-pos) currently running.
   */
  posVersion: string;
}

CurrencyCode

'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL'

Examples

import React, {useState} from 'react';

import {

reactExtension,

useApi,

Screen,

Text,

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

const SmartGridModal = () => {

const {currentSession, getSessionToken} =

useApi<'pos.home.modal.render'>().session;

const {shopId, userId, locationId, staffMemberId} = currentSession;

const [sessionToken, setSessionToken] = useState<string>();

getSessionToken().then((newToken) => {

setSessionToken(newToken);

});

return (

<Text>

shopId: {shopId}, userId: {userId}, locationId: {locationId}, staffId:

{staffMemberId}

</Text>

<Text>sessionToken: {sessionToken}</Text>

</Screen>

);

};

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

));

Examples

Access shop and location information

Description

Retrieve current session data including shop domain, location ID, and user information. This example shows how to access session properties to get shop context, enabling you to personalize experiences, make location-specific decisions, or pass shop identifiers to backend services.

React

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

const SmartGridModal = () => {
  const {currentSession, getSessionToken} =
    useApi<'pos.home.modal.render'>().session;

  const {shopId, userId, locationId, staffMemberId} = currentSession;
  const [sessionToken, setSessionToken] = useState<string>();

  getSessionToken().then((newToken) => {
    setSessionToken(newToken);
  });

  return (
    <Screen name="ScreenOne" title="Screen One Title">
      <Text>
        shopId: {shopId}, userId: {userId}, locationId: {locationId}, staffId:
        {staffMemberId}
      </Text>
      <Text>sessionToken: {sessionToken}</Text>
    </Screen>
  );
};

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

TS

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

export default extension('pos.home.modal.render', (root, api) => {
  const {session} = api;
  const {currentSession, getSessionToken} = session;
  const {shopId, userId, locationId, staffMemberId} = currentSession;

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

  const currentSessionText = root.createComponent(
    Text,
    {},
    `shopId: ${shopId}, userId: ${userId}, locationId: ${locationId}, staffId: ${staffMemberId}`,
  );
  const sessionTokenText = root.createComponent(
    Text,
    {},
    'sessionToken: undefined',
  );

  getSessionToken().then((newToken) => {
    sessionTokenText.children.forEach((child) => {
      sessionTokenText.removeChild(child);
    });
    sessionTokenText.appendChild(`sessionToken: ${newToken}`);
  });

  screen.appendChild(currentSessionText);
  screen.appendChild(sessionTokenText);
  root.appendChild(screen);
});

Anchor to best-practicesBest practices

Use appropriate identifiers: Distinguish between userId (authenticated account) and staffMemberId (pinned staff member) to implement correct permissions and personalization logic.
Implement location-aware features: Use locationId and currency information.
Secure backend communication: Use session tokens exclusively for backend API calls and never expose them in client-side logs or storage. validate tokens on your backend before processing requests.

Anchor to limitationsLimitations

Session tokens are only available when the authenticated user has proper app permissions enabled. Staff members who are pinned in but not authenticated can't generate tokens.
Session data is read-only and can't be modified through the API. Changes to shop settings, locations, or staff assignments require POS application updates.
Session tokens should only be used for communication with your app's configured backend service and can't be used for direct Shopify API calls from the client side.

Was this page helpful?