📘 Types Reference

This page describes all TypeScript types used by the NextShopKit SDK to help you confidently use and extend its functionality. These types power both the CartProvider and standalone API methods.

🛒 `LineItemInput`

export interface LineItemInput {
  merchandiseId: string;
  quantity: number;
}

Describes an item to add to the cart.

merchandiseId: Variant ID (Shopify ID)
quantity: How many units to add

🏷️ `CartAttribute`

export interface CartAttribute {
  key: string;
  value: string;
}

Represents a custom cart attribute, stored as key-value pairs.

👤 `BuyerIdentityInput`

export interface BuyerIdentityInput {
  email?: string;
  phone?: string;
  countryCode?: string;
  customerAccessToken?: string;
}

Buyer metadata to attach to the cart (e.g., for localization or customer login).

🧾 `CartLine`

export interface CartLine {
  id: string;
  quantity: number;
  merchandise: {
    id: string;
    title: string;
    product: {
      title: string;
      handle: string;
      metafields?: Array<{ key: string; value: string }>;
    };
    image?: { url: string; altText?: string };
    price: { amount: string; currencyCode: string };
  };
}

Represents a line item in the cart, including product and variant info.

💰 `CartCost`

export interface CartCost {
  totalAmount: { amount: string; currencyCode: string };
}

The total monetary cost of the cart.

🛍️ `ShopifyCart`

export interface ShopifyCart {
  id: string;
  checkoutUrl: string;
  lines: CartLine[];
  cost: CartCost;
  attributes?: CartAttribute[];
  buyerIdentity?: BuyerIdentityInput;
}

The full structure of a Shopify cart object returned by the SDK.

⚙️ `CartProviderConfig`

export interface CartProviderConfig {
  customAttributes?: CartAttributeDefinition[];
  productMetafields?: CustomMetafieldDefinition[];
  variantMetafields?: CustomMetafieldDefinition[];
  options?: {
    lineLimit?: number;
    resolveFiles?: boolean;
    renderRichTextAsHtml?: boolean;
    camelizeKeys?: boolean;
    transformCartAttributes?: (
      raw: CartAttribute[],
      casted: Record<string, any>,
      resolved: ResolvedAttributeInfo[]
    ) => Record<string, any> | Promise<Record<string, any>>;
    transformVariantMetafields?: (
      raw: Record<string, Record<string, string>>,
      casted: Record<string, any>,
      definitions: ResolvedMetafieldInfo[]
    ) => Record<string, any> | Promise<Record<string, any>>;
    transformProductMetafields?: (
      raw: Record<string, Record<string, string>>,
      casted: Record<string, any>,
      definitions: ResolvedMetafieldInfo[]
    ) => Record<string, any> | Promise<Record<string, any>>;
  };
}

export interface CustomMetafieldDefinition {
  field: string; // e.g., "custom.title"
  type: ShopifyCustomFieldType;
}

export interface CartAttributeDefinition {
  key: string; // e.g., "isGift"
  type: "string" | "boolean" | "integer" | "decimal" | "json" | "date"; // limited types
}

Configuration used across both standalone cart functions and the CartProvider.

🧩 `CartProviderProps`

export interface CartProviderProps {
  children: ReactNode;
  client: ShopifyClient;
  debug?: boolean;
  config?: CartProviderConfig;
}

Props accepted by <CartProvider>. You must pass a ShopifyClient instance.

🔌 `ShopifyClientConfig`

export interface ShopifyClientConfig {
  shop: string;
  token: string;
  apiVersion?: string;
  enableVercelCache?: boolean;
  enableMemoryCache?: boolean;
  defaultCacheTtl?: number;
  defaultRevalidate?: number;
}

Used to configure a new client via createShopifyClient(). Supports local + Vercel cache.

🧠 `ShopifyBaseClient`

export interface ShopifyBaseClient {
  fetchShopify(
    query: string,
    variables?: any,
    options?: FetchOptions
  ): Promise<any>;
  clearCache(): void;
  getCache(): Map<string, { timestamp: number; data: any }>;

  getProduct(args: GetProductOptions): Promise<FetchProductResult>;
  getCollection(args: GetCollectionOptions): Promise<FetchCollectionResult>;

  createCart(): Promise<ShopifyCart>;
  getCart(cartId: string, config?: CartProviderConfig): Promise<ShopifyCart>;
  addToCart(
    cartId: string,
    lines: LineItemInput[],
    config?: CartProviderConfig
  ): Promise<ShopifyCart>;
  removeFromCart(cartId: string, lineId: string): Promise<ShopifyCart>;
  updateCartItem(
    cartId: string,
    lineId: string,
    quantity: number
  ): Promise<ShopifyCart>;
  emptyCart(cartId: string): Promise<ShopifyCart>;
  applyDiscount(cartId: string, code: string): Promise<ShopifyCart>;
  removeDiscount(cartId: string): Promise<ShopifyCart>;
  updateCartAttributes(
    cartId: string,
    attributes: CartAttribute[]
  ): Promise<ShopifyCart>;
  updateBuyerIdentity(
    cartId: string,
    buyerIdentity: BuyerIdentityInput
  ): Promise<ShopifyCart>;
  mergeCarts(
    sourceCartId: string,
    destinationCartId: string
  ): Promise<ShopifyCart>;
}