Mockup Generation

Generate product mockup URLs with the SDK

Overview

The mockupUrl() function generates signed URLs for product mockups with your artwork. The returned URL can be used anywhere: img tags, CSS backgrounds, or any image processing pipeline.

For the underlying REST API endpoint, see the API reference.

Basic Usage

import { mockupUrl, config } from 'merchify';

// Configure once at app startup
config({
  accountId: 'YOUR_ACCOUNT_ID',
});

// Generate a mockup URL
const url = mockupUrl({
  productId: 'BEEB77',       // Product ID from catalog
  mockupId: 'FV1qjO',        // Mockup template ID
  design: [
    {
      type: 'image',
      imageUrl: 'https://example.com/artwork.png',
      placement: 'Front',
      alignment: 'center',
    }
  ],
  width: 1000,               // Output width in pixels
});

// Use in HTML
document.querySelector('img').src = url;

Design Elements

The design array contains one or more design elements. Each element can be an image or a solid color.

Image Element

Place artwork on the product:

{
  type: 'image',
  imageUrl: 'https://example.com/artwork.png',
  placement: 'Front',       // 'Front', 'Back', etc.
  alignment: 'center',      // Position within the print area
  width: 400,               // Optional: artwork width in pixels
  height: 400,              // Optional: artwork height in pixels
}

Color Element

Fill a print area with a solid color:

{
  type: 'color',
  hex: '#FF5733',           // Color in hex format
  placement: 'Back',
  alignment: 'center',
}

Multiple Placements

Add artwork to multiple print areas:

const url = mockupUrl({
  productId: 'BEEB77',
  mockupId: 'FV1qjO',
  design: [
    {
      type: 'image',
      imageUrl: 'https://example.com/front-design.png',
      placement: 'Front',
      alignment: 'center',
    },
    {
      type: 'image',
      imageUrl: 'https://example.com/back-design.png',
      placement: 'Back',
      alignment: 'top',
    }
  ],
  width: 1000,
});

Alignment Options

The alignment property controls where artwork is positioned within the print area:

center
Centered (default)
top
Top center
bottom
Bottom center
left
Left center
right
Right center
far-top
Far top edge
far-bottom
Far bottom edge
far-left
Far left edge
far-right
Far right edge
// Position artwork at the top of the print area
const url = mockupUrl({
  productId: 'BEEB77',
  mockupId: 'FV1qjO',
  design: [{
    type: 'image',
    imageUrl: 'https://example.com/logo.png',
    placement: 'Front',
    alignment: 'top',  // Logo at top of chest area
  }],
  width: 1000,
});

Aspect Ratio

Control the output image aspect ratio with the ar parameter:

16:9
ar: '16:9'

Default landscape

2:3
ar: '2:3'

Portrait (social/mobile)

// Generate a portrait mockup for social media
const url = mockupUrl({
  productId: 'BEEB77',
  mockupId: 'FV1qjO',
  design: [{ type: 'image', imageUrl: '...', placement: 'Front', alignment: 'center' }],
  width: 1000,
  ar: '2:3',  // Portrait aspect ratio
});

Options Reference

OptionTypeRequiredDescription
productIdstringYesProduct identifier from the catalog
mockupIdstringYesMockup template ID
designDesignElement[]YesArray of design elements (image or color)
widthnumberNoOutput width: 400, 600, 800, 1000 (default), 1200, 1400, 1600, 1800, 2000, 2500, 3000, 4000
variantIdstringNoVariant ID for color/size specific mockups
ar'16:9' | '2:3'NoAspect ratio for output image
grain0 | 1 | 2NoFilm grain effect: 0 (none), 1 (subtle), 2 (strong)

TypeScript Types

The SDK exports all types for full TypeScript support:

import type {
  MockupUrlOptions,
  DesignElement,
  ImageDesignElement,
  ColorDesignElement,
  ImageAlignment,
} from 'merchify';

// ImageDesignElement
interface ImageDesignElement {
  type: 'image';
  imageUrl: string;
  placement: string;
  alignment: ImageAlignment;
  width?: number;
  height?: number;
}

// ColorDesignElement
interface ColorDesignElement {
  type: 'color';
  hex: string;
  placement: string;
  alignment: ImageAlignment;
}

// ImageAlignment
type ImageAlignment =
  | 'center'
  | 'top' | 'bottom' | 'left' | 'right'
  | 'far-top' | 'far-bottom' | 'far-left' | 'far-right';