merchify

JavaScript/TypeScript SDK for product mockups and print-on-demand

Merchify provides a simple SDK for fetching product data and generating real-time merchandise mockups. Use it to visualize artwork on t-shirts, posters, mugs, and more.

Installation

npm install merchify
# or
yarn add merchify
# or
pnpm add merchify

Quick Start

import { getProduct, listProducts, generateMockupUrl } from 'merchify';

// Fetch a product by ID
const product = await getProduct('BEEB77');
console.log(product.name); // "Bella + Canvas 3001 Unisex Jersey Short Sleeve Tee"

// List all products
const products = await listProducts({ limit: 10 });
console.log(`Found ${products.length} products`);

// Generate a mockup URL
const mockupUrl = generateMockupUrl({
  productId: 'BEEB77',
  variantId: 'white-sm',
  artworkUrl: 'https://example.com/artwork.png',
  placement: 'Front',
  alignment: 'center'
});
console.log(mockupUrl); // URL to mockup image

Configuration

Configure the SDK to point to your Merchify endpoint:

import { config } from 'merchify';

config({
  endpoint: 'https://api.merchify.com',
  mockupUrl: 'https://mockup.merchify.com',
  accountId: 'your-account-id',
  mode: 'live' // or 'mock' for development
});

Environment Variables (Next.js):

NEXT_PUBLIC_MERCHIFY_ENDPOINT=https://api.merchify.com
NEXT_PUBLIC_MERCHIFY_MOCKUP_URL=https://mockup.merchify.com
NEXT_PUBLIC_MERCHIFY_ACCOUNT_ID=your-account-id

The SDK automatically reads these environment variables if not configured explicitly.

Core Functions

Product Data

// Get a single product
const product = await getProduct(productId: string, options?: {
  endpoint?: string;
  mode?: 'mock' | 'live' | 'meilisearch';
});

// List products
const products = await listProducts(options?: {
  limit?: number;
  offset?: number;
  endpoint?: string;
  mode?: 'mock' | 'live' | 'meilisearch';
});

Product Object Structure:

{
  id: string;              // Product ID (e.g., "BEEB77")
  name: string;            // Product name
  description?: string;    // Product description
  basePrice: number;       // Base price in cents
  variants: Variant[];     // Color/size variants
  placements: Placement[]; // Print areas (Front, Back, etc.)
  mockup: {
    blankUrl: string;      // Blank product image URL
  };
}

Mockup Generation

import { generateMockupUrl } from 'merchify';

const url = generateMockupUrl({
  productId: string;          // Required: Product ID
  variantId?: string;         // Optional: Specific variant (color/size)
  artworkUrl: string;         // Required: URL to artwork image
  placement?: string;         // Optional: Print area (default: 'Front')
  alignment?: ImageAlignment; // Optional: How to position artwork
  mode?: 'mock' | 'live';     // Optional: Mock or live rendering
});

// ImageAlignment options:
// 'center' | 'top' | 'bottom' | 'left' | 'right' |
// 'far-left' | 'far-right' | 'far-top' | 'far-bottom'

React Hooks (Optional)

For React applications, use the React-specific exports:

import { useRealtimeMockup } from 'merchify/react';

function MyComponent() {
  const { mockupUrl, isGenerating } = useRealtimeMockup({
    productId: 'BEEB77',
    artworkUrl: artwork.src,
    placement: 'Front',
    alignment: 'center'
  });

  return <img src={mockupUrl} alt="Product mockup" />;
}

TypeScript Support

Full TypeScript definitions are included. Import types:

import type {
  CatalogProduct,
  Variant,
  Placement,
  ImageAlignment
} from 'merchify';

Development Mode

Use mock mode for development without API calls:

config({ mode: 'mock' });

// Returns mock product data
const product = await getProduct('BEEB77');

API Reference

See full API documentation at: https://docs.merchify.com/sdk

React Components

For pre-built React components, install merchify-ui:

npm install merchify-ui

See: merchify-ui on npm

Examples

• Next.js Example
• Basic Product Display

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Docs: docs.merchify.com

License

MIT © driuqzy

Built for developers. Optimized for LLMs. 🤖

This SDK is designed to work seamlessly with AI coding assistants like Claude, GitHub Copilot, and Cursor. Clear types, explicit examples, and predictable patterns make it easy for LLMs to generate correct code.