---
title: Session API
description: >-
  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.
api_version: 2024-10
api_name: pos-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2024-10/target-apis/standard-apis/session-api
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2024-10/target-apis/standard-apis/session-api.md
---

# 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.

## SessionApi

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](https://help.shopify.com/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions).

* currentSession

  Session

  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.

* 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](https://en.wikipedia.org/wiki/OpenID#OpenID_Connect_\(OIDC\)) 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. Contains authentication details, location context, and configuration settings that remain constant for the duration of the session.

* locationId

  The unique numeric identifier for the physical retail location where this POS device is currently operating. Locations represent distinct retail sites, warehouses, or pop-up shops within a merchant's business. This determines which inventory is available, which staff can access the POS, and which location appears on receipts and orders. Commonly used for location-specific inventory queries, sales reports, or implementing location-based features.

  ```ts
  number
  ```

* shopDomain

  The shop's \`.myapi.com\` domain name (for example, \`"my-store.myapi.com"\`). This is the shop's permanent Shopify domain, not custom domains. Commonly used for constructing API URLs, identifying the shop in external systems, or building shop-specific links.

  ```ts
  string
  ```

* shopId

  The unique numeric identifier for the Shopify shop currently logged into POS. This ID is consistent across all Shopify systems and APIs. Commonly used for shop-specific data queries, API authentication, or multi-shop configurations.

  ```ts
  number
  ```

* staffMemberId

  The unique numeric identifier for the staff member currently pinned into the POS session. This represents who is actively using the POS for transactions, which may differ from \`userId\` when a manager is logged in but a different staff member is pinned for sales attribution. Returns \`undefined\` when no staff member is pinned. Commonly used for sales attribution, commission tracking, or staff-specific workflows.

  ```ts
  number
  ```

* userId

  The unique numeric identifier for the Shopify account currently authenticated on POS. This represents the logged-in user's account, which may be the shop owner, an admin, or a staff member with POS access. This ID can differ from \`staffMemberId\` when a different staff member is pinned in for the transaction. Commonly used for user-specific permissions, audit trails, or tracking who performed actions.

  ```ts
  number
  ```

```ts
export interface Session {
  /**
   * The unique numeric identifier for the Shopify shop currently logged into POS. This ID is consistent across all Shopify systems and APIs. Commonly used for shop-specific data queries, API authentication, or multi-shop configurations.
   */
  shopId: number;

  /**
   * The unique numeric identifier for the Shopify account currently authenticated on POS. This represents the logged-in user's account, which may be the shop owner, an admin, or a staff member with POS access. This ID can differ from `staffMemberId` when a different staff member is pinned in for the transaction. Commonly used for user-specific permissions, audit trails, or tracking who performed actions.
   */
  userId: number;

  /**
   * The shop's `.myapi.com` domain name (for example, `"my-store.myapi.com"`). This is the shop's permanent Shopify domain, not custom domains. Commonly used for constructing API URLs, identifying the shop in external systems, or building shop-specific links.
   */
  shopDomain: string;

  /**
   * The unique numeric identifier for the physical retail location where this POS device is currently operating. Locations represent distinct retail sites, warehouses, or pop-up shops within a merchant's business. This determines which inventory is available, which staff can access the POS, and which location appears on receipts and orders. Commonly used for location-specific inventory queries, sales reports, or implementing location-based features.
   */
  locationId: number;

  /**
   * The unique numeric identifier for the staff member currently pinned into the POS session. This represents who is actively using the POS for transactions, which may differ from `userId` when a manager is logged in but a different staff member is pinned for sales attribution. Returns `undefined` when no staff member is pinned. Commonly used for sales attribution, commission tracking, or staff-specific workflows.
   */
  staffMemberId?: number;
}
```

## Best 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` 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.

## Limitations

* 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.

## Examples

Learn how to access session information and generate secure authentication tokens for backend communication.

### 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

  ```tsx
  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

  ```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);
  });
  ```