Prisma Models

Overview

This page provides detailed documentation for each Prisma model, including field descriptions, constraints, relationships, and usage examples.

All models are defined in /prisma/schema.prisma and managed through Prisma ORM for type-safe database access.

Session Model

Manages Shopify OAuth sessions for authenticated store connections. Supports both online (user-specific) and offline (app-level) access tokens.

Schema Definition

model Session {
  id            String    @id
  shop          String    @db.VarChar(255)
  state         String    @db.VarChar(255)
  isOnline      Boolean   @default(false)
  scope         String?   @db.Text
  expires       DateTime?
  accessToken   String    @db.Text
  userId        BigInt?
  firstName     String?   @db.VarChar(255)
  lastName      String?   @db.VarChar(255)
  email         String?   @db.VarChar(255)
  accountOwner  Boolean   @default(false)
  locale        String?   @db.VarChar(10)
  collaborator  Boolean?
  emailVerified Boolean?

  @@index([shop])
}

Field Descriptions

String

required

Primary Key - Unique session identifier generated during OAuth flow.Format: Combination of shop domain and session type (online/offline).

shop

String

required

Shop Domain - The myshopify.com domain of the connected store.

Max length: 255 characters
Indexed for fast lookups
Example: "example-store.myshopify.com"

state

String

required

OAuth State - Security token used during OAuth flow to prevent CSRF attacks.

Max length: 255 characters
Validated during callback

isOnline

Boolean

default:"false"

Session Type - Determines if this is a user-specific (online) or app-level (offline) session.

true: Online session (expires, user-specific)
false: Offline session (permanent, app-level access)

scope

String?

OAuth Scopes - Comma-separated list of Shopify API permissions granted.

Stored as TEXT field
Example: "read_products,write_products,read_orders"

expires

DateTime?

Expiration Time - When the session expires (online sessions only).

Null for offline sessions
Used to determine if re-authentication is needed

accessToken

String

required

Access Token - Shopify API access token for making authenticated requests.

Stored as TEXT (encrypted in production)
Required for all Shopify API calls

userId

BigInt?

User ID - Shopify user ID for online sessions.

Null for offline sessions
Links session to specific Shopify admin user

firstName

String?

User’s first name from Shopify account (max 255 chars).

lastName

String?

User’s last name from Shopify account (max 255 chars).

String?

User’s email address from Shopify account (max 255 chars).

accountOwner

Boolean

default:"false"

Owner Status - Indicates if the user is the shop owner.

Used for permission checks
Only shop owners can access certain features

locale

String?

User Locale - Language/region preference (max 10 chars).

Example: "en-US", "es-MX"
Used for localization

collaborator

Boolean?

Indicates if the user is a collaborator (staff member).

emailVerified

Boolean?

Whether the user’s email has been verified by Shopify.

Usage Examples

import { prisma } from './db.server';

const session = await prisma.session.findFirst({
  where: {
    shop: 'example-store.myshopify.com',
    isOnline: false, // Get offline session
  },
});

ShopConfiguration Model

Stores platform-specific configuration and API credentials for Ecomdrop and Dropi integrations.

Schema Definition

model ShopConfiguration {
  id                      String   @id @default(uuid())
  shop                    String   @unique @db.VarChar(255)
  ecomdropApiKey          String?  @db.Text
  nuevoPedidoFlowId       String?  @db.VarChar(255)
  carritoAbandonadoFlowId String?  @db.VarChar(255)
  dropiStoreName          String?  @db.VarChar(255)
  dropiCountry            String?  @db.VarChar(10)
  dropiToken              String?  @db.Text
  createdAt               DateTime @default(now())
  updatedAt               DateTime @updatedAt

  @@index([shop])
}

Field Descriptions

String

required

Primary Key - Auto-generated UUID.Format: Standard UUID v4

shop

String

required

Shop Domain - Unique shop identifier.

Max length: 255 characters
Unique constraint ensures one config per shop
Example: "example-store.myshopify.com"

ecomdropApiKey

String?

Ecomdrop API Key - Authentication key for Ecomdrop platform.

Stored as TEXT (encrypted recommended)
Required for flow automation features
Obtained from Ecomdrop dashboard

nuevoPedidoFlowId

String?

New Order Flow ID - Ecomdrop flow identifier for new order automation.

Max length: 255 characters
Triggers when new orders are created
Configured in Ecomdrop platform

carritoAbandonadoFlowId

String?

Abandoned Cart Flow ID - Ecomdrop flow identifier for cart abandonment.

Max length: 255 characters
Triggers for abandoned cart recovery
Configured in Ecomdrop platform

dropiStoreName

String?

Dropi Store Name - Store identifier in Dropi platform.

Max length: 255 characters
Used for product catalog access
Example: "my-dropshipping-store"

dropiCountry

String?

Dropi Country - Country/region for Dropi operations.

Max length: 10 characters
ISO country code recommended
Example: "MX", "US"

dropiToken

String?

Dropi Authentication Token - API token for Dropi platform access.

Stored as TEXT (encrypted recommended)
Required for product imports and order fulfillment
Obtained from Dropi account settings

createdAt

DateTime

default:"now()"

Creation Timestamp - When the configuration was first created.Auto-generated on record creation.

updatedAt

DateTime

Update Timestamp - Last modification time.Auto-updated on any field change.

Usage Examples

const config = await prisma.shopConfiguration.findUnique({
  where: { shop: 'example-store.myshopify.com' },
});

if (!config?.ecomdropApiKey) {
  // Redirect to settings page
}

Security Best Practice: Always encrypt sensitive fields like ecomdropApiKey and dropiToken before storing in the database.

ProductAssociation Model

Tracks the relationship between Dropi products and imported Shopify products, including import settings and preferences.

Schema Definition

model ProductAssociation {
  id                    String   @id @default(uuid())
  shop                  String   @db.VarChar(255)
  dropiProductId        String   @db.VarChar(255)
  shopifyProductId      String   @db.VarChar(255)
  dropiProductName      String?  @db.VarChar(500)
  shopifyProductTitle   String?  @db.VarChar(500)
  importType            String   @db.VarChar(50)
  dropiVariations       String?  @db.Text
  saveDropiName         Boolean  @default(true)
  saveDropiDescription  Boolean  @default(true)
  customPrice           String?  @db.VarChar(50)
  useSuggestedBarcode   Boolean  @default(false)
  saveDropiImages       Boolean  @default(true)
  createdAt             DateTime @default(now())
  updatedAt             DateTime @updatedAt

  @@unique([shop, dropiProductId, shopifyProductId])
  @@index([shop])
  @@index([dropiProductId])
  @@index([shopifyProductId])
}

Field Descriptions

String

required

Primary Key - Auto-generated UUID.

shop

String

required

Shop Domain - The store this association belongs to.

Max length: 255 characters
Indexed for filtering by shop

dropiProductId

String

required

Dropi Product ID - Unique identifier from Dropi catalog.

Max length: 255 characters
Indexed for reverse lookups
Part of composite unique constraint

shopifyProductId

String

required

Shopify Product ID - GraphQL GID of the imported product.

Max length: 255 characters
Format: "gid://shopify/Product/123456789"
Indexed for product updates
Part of composite unique constraint

dropiProductName

String?

Original Dropi Name - Product name from Dropi catalog.

Max length: 500 characters
Stored for reference and sync

shopifyProductTitle

String?

Shopify Title - Current product title in Shopify.

Max length: 500 characters
May differ from Dropi name if customized

importType

String

required

Import Type - Method used to import the product.

Max length: 50 characters
Values: "single", "bulk", "auto"
Used for tracking and analytics

dropiVariations

String?

Variant Mappings - JSON data mapping Dropi variants to Shopify variants.

Stored as TEXT
Format: JSON string with variant IDs and SKUs
Used for order fulfillment routing

saveDropiName

Boolean

default:"true"

Save Name Preference - Whether to use Dropi’s product name.

true: Use Dropi name
false: Use custom name

saveDropiDescription

Boolean

default:"true"

Save Description Preference - Whether to use Dropi’s description.

true: Import Dropi description
false: Use custom description

customPrice

String?

Custom Pricing - Custom price override or markup formula.

Max length: 50 characters
Examples: "29.99", "cost*1.5", "+10"

useSuggestedBarcode

Boolean

default:"false"

Barcode Preference - Whether to use Dropi’s suggested barcode.

true: Use Dropi barcode
false: Generate or use custom barcode

saveDropiImages

Boolean

default:"true"

Image Import Preference - Whether to import product images from Dropi.

true: Import Dropi images
false: Use custom images

createdAt

DateTime

default:"now()"

Import Timestamp - When the product was first associated.

updatedAt

DateTime

Last Sync Time - Last time the association was updated.

Usage Examples

const association = await prisma.productAssociation.create({
  data: {
    shop,
    dropiProductId: 'DROPI-12345',
    shopifyProductId: 'gid://shopify/Product/987654321',
    dropiProductName: 'Premium Wireless Earbuds',
    shopifyProductTitle: 'Premium Wireless Earbuds',
    importType: 'single',
    dropiVariations: JSON.stringify({
      variants: [
        { dropiId: 'VAR-1', shopifyId: 'gid://shopify/ProductVariant/111' },
        { dropiId: 'VAR-2', shopifyId: 'gid://shopify/ProductVariant/222' },
      ],
    }),
    saveDropiName: true,
    saveDropiDescription: true,
    customPrice: '49.99',
    useSuggestedBarcode: false,
    saveDropiImages: true,
  },
});

The composite unique constraint [shop, dropiProductId, shopifyProductId] ensures that each Dropi product can only be associated with a specific Shopify product once per shop.

AIConfiguration Model

Stores AI agent configuration, knowledge base, and behavioral rules for personalized customer support.

Schema Definition

model AIConfiguration {
  id                      String   @id @default(uuid())
  shop                    String   @unique @db.VarChar(255)
  agentName               String?  @db.VarChar(255)
  companyName             String?  @db.VarChar(255)
  companyDescription      String?  @db.Text
  paymentMethods          String?  @db.Text
  companyPolicies         String?  @db.Text
  faq                     String?  @db.Text
  postSaleFaq             String?  @db.Text
  rules                   String?  @db.Text
  notifications           String?  @db.Text
  createdAt               DateTime @default(now())
  updatedAt               DateTime @updatedAt

  @@index([shop])
}

Field Descriptions

String

required

Primary Key - Auto-generated UUID.

shop

String

required

Shop Domain - Unique shop identifier.

Max length: 255 characters
Unique constraint ensures one AI config per shop

agentName

String?

AI Agent Name - Custom name for the chatbot/assistant.

Max length: 255 characters
Example: "Sofia", "Support Assistant"
Displayed to customers during interactions

companyName

String?

Company Name - Store or business name.

Max length: 255 characters
Used in AI responses for personalization
Example: "TechGadgets Store"

companyDescription

String?

Business Description - Overview of the business and offerings.

Stored as TEXT (no length limit)
Provides context for AI responses
Includes mission, values, product categories

paymentMethods

String?

Payment Methods - Accepted payment options.

Stored as TEXT
Format: Free-form or structured (JSON)
Example: "Credit cards, PayPal, Mercado Pago, OXXO"

companyPolicies

String?

Store Policies - Return, shipping, and general policies.

Stored as TEXT
Includes return windows, shipping times, warranty info
Used by AI to answer policy questions

faq

String?

Pre-Sale FAQ - Common questions before purchase.

Stored as TEXT
Format: Question-answer pairs
Topics: Product info, sizing, availability

postSaleFaq

String?

Post-Sale FAQ - Questions about orders and support.

Stored as TEXT
Topics: Order tracking, returns, exchanges
Used for customer support automation

rules

String?

AI Behavior Rules - Guidelines for AI agent behavior.

Stored as TEXT
Example: "Always be friendly and professional"
Defines tone, escalation triggers, boundaries

notifications

String?

Notification Settings - Configuration for alerts and notifications.

Stored as TEXT
Format: JSON recommended
Controls when/how to notify store owners

createdAt

DateTime

default:"now()"

Configuration Created - Initial setup timestamp.

updatedAt

DateTime

Last Modified - Last time the configuration was updated.

Usage Examples

const aiConfig = await prisma.aIConfiguration.findUnique({
  where: { shop: 'example-store.myshopify.com' },
});

if (!aiConfig) {
  // Show setup wizard
}

Best Practice: Store FAQ data as JSON for easier parsing and updating. This allows structured querying and better AI context management.

Common Patterns

Multi-Shop Support

All models use shop as a key field for multi-tenancy:

// Always scope queries by shop
const data = await prisma.model.findMany({
  where: { shop },
});

Timestamps

Models with createdAt and updatedAt provide automatic timestamp tracking:

// updatedAt is automatically updated
await prisma.model.update({
  where: { id },
  data: { field: newValue },
  // updatedAt will be set to now()
});

Upsert Operations

Use upsert for create-or-update logic:

const config = await prisma.shopConfiguration.upsert({
  where: { shop },
  create: { shop, /* initial data */ },
  update: { /* updated fields */ },
});

Database Schema - Schema overview and ER diagram

API Overview

Endpoints

Database

Overview

Session Model

Schema Definition

Field Descriptions

Usage Examples

ShopConfiguration Model

Schema Definition

Field Descriptions

Usage Examples

ProductAssociation Model

Schema Definition

Field Descriptions

Usage Examples

AIConfiguration Model

Schema Definition

Field Descriptions

Usage Examples

Common Patterns

Multi-Shop Support

Timestamps

Upsert Operations

API Overview

Endpoints

Database

Documentation Index

​Overview

​Session Model

​Schema Definition

​Field Descriptions

​Usage Examples

​ShopConfiguration Model

​Schema Definition

​Field Descriptions

​Usage Examples

​ProductAssociation Model

​Schema Definition

​Field Descriptions

​Usage Examples

​AIConfiguration Model

​Schema Definition

​Field Descriptions

​Usage Examples

​Common Patterns

​Multi-Shop Support

​Timestamps

​Upsert Operations

​Related Documentation

Overview

Session Model

Schema Definition

Field Descriptions

Usage Examples

ShopConfiguration Model

Schema Definition

Field Descriptions

Usage Examples

ProductAssociation Model

Schema Definition

Field Descriptions

Usage Examples

AIConfiguration Model

Schema Definition

Field Descriptions

Usage Examples

Common Patterns

Multi-Shop Support

Timestamps

Upsert Operations

Related Documentation