Skip to main content
Session storage is a critical component of Shopify apps that allows you to persist user authentication data and other session information across requests. The Shopify App JavaScript SDK provides a flexible session storage system with multiple database adapters.

​
What is Session Storage?

When a user installs or accesses your Shopify app, the OAuth flow generates a session containing:
  • Access tokens for making API requests
  • Shop information
  • User details (for online sessions)
  • Token expiration times
  • OAuth state information
These sessions must be stored securely and retrieved efficiently to maintain app functionality.

​
The SessionStorage Interface

All session storage implementations in the SDK implement the SessionStorage interface, which defines five core methods: 
interface SessionStorage {
  storeSession(session: Session): Promise<boolean>;
  loadSession(id: string): Promise<Session | undefined>;
  deleteSession(id: string): Promise<boolean>;
  deleteSessions(ids: string[]): Promise<boolean>;
  findSessionsByShop(shop: string): Promise<Session[]>;
}

​
Key Methods

​
storeSession
(session: Session) => Promise<boolean>
Creates or updates a session in storage. Returns true on success.
​
loadSession
(id: string) => Promise<Session | undefined>
Retrieves a session by its ID. Returns undefined if not found.
​
deleteSession
(id: string) => Promise<boolean>
Deletes a single session from storage.
​
deleteSessions
(ids: string[]) => Promise<boolean>
Deletes multiple sessions in a single operation.
​
findSessionsByShop
(shop: string) => Promise<Session[]>
Finds all sessions associated with a specific shop.

​
Available Adapters

The SDK provides official adapters for various database systems:

PostgreSQL

Production-ready relational database

MySQL

Popular relational database

Redis

High-performance in-memory store

MongoDB

Flexible document database

DynamoDB

AWS serverless database

SQLite

Lightweight file-based database

Drizzle

Type-safe ORM for SQL databases

Prisma

Modern database toolkit

Cloudflare KV

Edge-compatible key-value store

Memory

In-memory storage for development

​
Choosing an Adapter

Consider these factors when selecting a session storage adapter:

​
Production Apps

For production environments, choose a persistent database:
  • PostgreSQL or MySQL - Best for traditional server deployments
  • Redis - Excellent for high-traffic apps requiring fast access
  • MongoDB - Good for flexible schema requirements
  • DynamoDB - Ideal for AWS serverless architectures
  • Prisma/Drizzle - When using these ORMs in your stack

​
Serverless/Edge Deployments

  • Cloudflare KV - Perfect for Cloudflare Workers
  • DynamoDB - Great for AWS Lambda
  • Redis - Works well with serverless when using managed services

​
Development & Testing

  • Memory - Quick setup, no configuration needed
  • SQLite - Simple file-based storage for local development
Never use MemorySessionStorage in production. Sessions are lost when the process restarts.

​
Session Data Structure

Sessions store the following information: 
{
  id: string;              // Unique session identifier
  shop: string;            // Shop domain (e.g., 'example.myshopify.com')
  state: string;           // OAuth state parameter
  isOnline: boolean;       // Online vs offline session
  scope?: string;          // Granted API scopes
  expires?: Date;          // Session expiration time
  accessToken?: string;    // API access token
  refreshToken?: string;   // Token refresh capability
  refreshTokenExpires?: Date;
  // Online session user info
  userId?: number;
  firstName?: string;
  lastName?: string;
  email?: string;
  accountOwner?: boolean;
  locale?: string;
  collaborator?: boolean;
  emailVerified?: boolean;
}

​
Database Schema Requirements

Most adapters automatically create the necessary tables/collections, but you should understand the schema:

​
Relational Databases (PostgreSQL, MySQL, SQLite)

The default table structure includes:
  • Primary key on id
  • Indexed shop column for efficient lookups
  • All session fields as columns
  • Automatic migrations handled by the SDK

​
Document Databases (MongoDB)

Stores sessions as documents with the session ID as the primary key.

​
Key-Value Stores (Redis, KV)

Uses the session ID as the key and serialized JSON as the value.

​
Migration Support

Relational database adapters include built-in migration support:
  • Automatic schema creation on first run
  • Migration tracking to prevent duplicate migrations
  • Backwards-compatible schema updates
The SDK handles migrations automatically. You don’t need to run migration commands manually.

​
Security Considerations

Session storage contains sensitive data including access tokens. Always:
  • Use encrypted connections to your database
  • Restrict database access with proper authentication
  • Use environment variables for connection credentials
  • Never commit credentials to version control
  • Enable encryption at rest when available

​
Next Steps

SessionStorage Interface

Detailed interface documentation

Database Adapters

Setup guides for each adapter

Build docs developers (and LLMs) love

Get started for freeTalk to us