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.

Anchor to Use casesUse cases

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

Support

Targets (28)

Supported targets

Anchor to PropertiesProperties

The SessionApi object provides access to current session information and authentication. Access these properties through shopify.session to retrieve shop data and generate secure tokens. These properties 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
```

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

jsx

import {render} from 'preact';

export default async () => {

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

};

const Extension = () => {

const session = shopify.session.currentSession;

return (

<s-page heading="Current Session">

<s-scroll-box>

<s-stack direction="block">

<s-section heading="Shop Information">

<s-text>Shop ID: {session.shopId}</s-text>

<s-text>Shop Domain: {session.shopDomain}</s-text>

<s-text>Currency: {session.currency}</s-text>

</s-section>

<s-section heading="User & Staff">

<s-text>User ID: {session.userId}</s-text>

<s-text>Location ID: {session.locationId}</s-text>

{session.staffMemberId && (

<s-text>Staff Member ID: {session.staffMemberId}</s-text>

)}

</s-section>

<s-section heading="System">

<s-text>POS Version: {session.posVersion}</s-text>

</s-section>

</s-stack>

</s-scroll-box>

</s-page>

);

};

Examples

Description

Access comprehensive session information including shop details, user data, and location information. This example shows how to use `shopify.session.currentSession` to retrieve the shop ID, domain, currency, user ID, location ID, staff member ID, and POS version. Use this data to build location-aware features and personalized experiences.

jsx

import {render} from 'preact';

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

const Extension = () => {
  const session = shopify.session.currentSession;

  return (
    <s-page heading="Current Session">
      <s-scroll-box>
        <s-stack direction="block">
          <s-section heading="Shop Information">
            <s-text>Shop ID: {session.shopId}</s-text>
            <s-text>Shop Domain: {session.shopDomain}</s-text>
            <s-text>Currency: {session.currency}</s-text>
          </s-section>
          <s-section heading="User & Staff">
            <s-text>User ID: {session.userId}</s-text>
            <s-text>Location ID: {session.locationId}</s-text>
            {session.staffMemberId && (
              <s-text>Staff Member ID: {session.staffMemberId}</s-text>
            )}
          </s-section>
          <s-section heading="System">
            <s-text>POS Version: {session.posVersion}</s-text>
          </s-section>
        </s-stack>
      </s-scroll-box>
    </s-page>
  );
};

Description

Access session data and generate authentication tokens. This example shows how to access shop details, user information, and location data through `shopify.session`, and use `shopify.session.getSessionToken()` to generate tokens for authenticated requests to your backend services.

jsx

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

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

const Extension = () => {
  const [sessionToken, setSessionToken] = useState('');
  const {shopId, userId, locationId, staffMemberId} = shopify.session.currentSession;

  useEffect(() => {
    shopify.session.getSessionToken().then((newToken) => {
      setSessionToken(newToken);
    });
  }, []);

  return (
    <s-page heading="Screen One Title">
      <s-scroll-box>
        <s-text>
          shopId: {shopId}, userId: {userId}, locationId: {locationId}, staffId: {staffMemberId}
        </s-text>
        <s-text>sessionToken: {sessionToken}</s-text>
      </s-scroll-box>
    </s-page>
  );
};

Anchor to Best practicesBest practices

Handle authentication properly: Check for undefined session tokens and implement proper fallback behavior when authentication fails or permissions are insufficient.
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 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?