Skip to main content
The Mage SDK is injected into the storefront at runtime via window.MageSDK. Since it isn’t an npm package, TypeScript won’t know about it by default. You can add full type support by creating a declaration file in your project.

​
Setup

Create a file called mage-sdk.d.ts anywhere in your project (e.g. the root, or a types/ folder):
mage-sdk.d.ts
interface MageSDKResponse<T = unknown> {
  success: boolean;
  error?: string;
  data?: T;
}

interface MageVipTier {
  id: string;
  name: string;
  description: string | null;
  pointsRequired: number;
  pointsMultiplier: number;
  badgeImageUrl: string | null;
  badgeColor: string | null;
  rewards: Array<{
    id: string;
    name: string;
    discountType: string | null;
    discountAmount: number | null;
    pointsCost: number;
    isActive: boolean;
  }>;
}

interface MageCustomerDetails {
  id: string;
  shopifyCustomerId: string;
  email: string;
  firstName: string;
  lastName: string;
  points: number;
  lifetimePoints: number;
  redeemedPoints: number;
  isExcluded: boolean;
  dateOfBirth: string | null;
  referralCode: string | null;
  referralUrl: string | null;
  tier: MageVipTier | null;
  tierProgressValue: number;
  earningHistory: Array<{
    id: string;
    earningRuleId: string;
    status: string;
    points: number;
    createdAt: string;
    earningRule: { id: string; name: string };
  }>;
  referralEarnings: Array<{
    id: string;
    type: string;
    status: string;
    friendEmail: string;
    createdAt: string;
  }>;
  createdAt: string;
  updatedAt: string;
}

interface MageReward {
  id: string;
  name: string;
  description: string;
  pointsCost: number;
  category: string;
  discountType: string | null;
  tier: MageVipTier | null;
  minimumSpend?: string;
  productMetadata?: {
    productId?: string;
    productTitle?: string;
    productImage?: string | null;
    productHandle?: string | null;
  } | null;
}

interface MageCustomerReward {
  id: string;
  rewardName: string;
  rewardDescription?: string;
  points: number;
  discountCode: string;
  discountType?: string | null;
  status: string;
  createdAt: string;
  expiresAt: string | null;
}

interface MageEarningRule {
  id: string;
  name: string;
  description: string | null;
  action: string;
  category: string;
  isActive: boolean;
  pointsToGive: number;
  customerFacingLabel: string | null;
  callToActionUrl: string | null;
  customerEarningRule?: {
    id: string;
    earningRuleId: string;
    status: string;
    points: number;
    createdAt: string;
  } | null;
}

interface MageReferralStats {
  summary: {
    totalReferrals: number;
    pending: number;
    friendConverted: number;
    completed: number;
    expired: number;
    availableRewards: number;
  };
  referrals: Array<{
    id: string;
    friendEmail: string;
    status: string;
    createdAt: string;
  }>;
}

interface MageReferralLink {
  enabled: boolean;
  referralCode?: string;
  referralUrl?: string;
  stats?: {
    totalReferred: number;
    completedReferrals: number;
    pendingReferrals: number;
  };
  socialSharing?: {
    twitter: boolean;
    twitterMessage: string | null;
    facebook: boolean;
    email: boolean;
    whatsapp: boolean;
    whatsappMessage: string | null;
  };
  message?: string;
}

interface MageLoyaltySDK {
  // Customers
  getCustomerDetails(): Promise<MageSDKResponse<{ customer: MageCustomerDetails }>>;
  getCustomerVipTier(): Promise<MageSDKResponse<{ tier: MageVipTier | null; tierProgressValue: number }>>;
  updateCustomerDob(dob: string): Promise<boolean>;

  // Rewards
  getShopRewards(): Promise<MageSDKResponse<{ regularRewards: MageReward[]; tieredRewards: MageReward[] }>>;
  getCustomerRewards(): Promise<MageSDKResponse<{ customerRewards: MageCustomerReward[] }>>;
  redeemReward(rewardId: string): Promise<MageSDKResponse<{ discountCode: string; reward: { name: string; discountType: string } }>>;

  // VIP Tiers
  getShopVipTiers(): Promise<MageSDKResponse<{ tiers: MageVipTier[]; entryMethod: string; currencySymbol: string; pointsMultiplierMode: string | null }>>;

  // Earning Rules
  getEarningRules(): Promise<MageSDKResponse<{ earningRules: MageEarningRule[] }>>;

  // Referrals
  getCustomerReferralStats(): Promise<MageSDKResponse<MageReferralStats>>;
  getReferralLink(): Promise<MageSDKResponse<MageReferralLink>>;

  // Sidebar
  openSidebar(): void;
  closeSidebar(): void;
}

interface Window {
  MageSDK: MageLoyaltySDK;
}
Make sure the file is included in your tsconfig.json (it will be automatically if it’s inside your project root or include paths).

​
Usage

Once the declaration file is in place, you get full autocomplete and type checking: 
// TypeScript now knows about window.MageSDK
const resp = await window.MageSDK.getCustomerDetails();

if (resp.success && resp.data) {
  const { customer } = resp.data;
  console.log(customer.points);    // number
  console.log(customer.tier?.name); // string | undefined
}