Mockup Generator API

To generate mockups, first you need to decide on which products you want them. API methods on retrieving products and variants can be found in the Product Catalog documentation.

Note: Remember to distinguish the difference between a product id and a variant id. Some API endpoints require id from a variant and some from a product.

Print files

A print file defines resolution which should be used to create a mockup or to submit an actual order.

Information about product variant print files can be retrieved from the print file endpoint.

For example, a 10×10 poster requires 1500×1500 pixel print file to produce a 150 DPI print. You can use higher resolution files to achieve a better result, but keep the side aspect ratio same as the defined for the print file. That means, if you use a 3000×3000 pixel file, it will produce 300 DPI print. But if you use 3000×1500 pixel file (different aspect ratio) on a 10×10 poster, some cropping will occur. Print file's fill_mode parameter defines if cropping will happen or the file will be fitted on the resulting print area of the product.

Some print files can be rotated. can_rotate field defines this feature. This mostly applies to wall art products and should be used if you want to generate a horizontal or a vertical product mockup.

Wall art print files are defined horizontal. If you wish to create a vertical mockup, you can rotate the file's print file and the generated mockup will be in given orientation. For example, 16×12 poster print file is 2400×1800 pixels which generates it horizontal. If you wish to get a vertical mockup, you create the print file as 1800×2400 pixels. The same strategy applies when you submit an order.

Print files are often re-used for multiple variants and products. For example, a 14×14 poster uses the same print file as framed poster. Most of the t-shirt front prints use the same print file too.

Note: When you generate mockups there is no need to provide a full sized print file. Mockups are generated up to 1000px wide, so you can downscale your print file to 1000px. This will reduce the processing time on your and on Printful's side.

Mockup generation

Mockup generation requires some time, that is why it cannot happen in real time.

When you request a mockup to be generated, a task is created and you receive the task key which can then be used to retrieve the generated mockup list. We cannot guarantee that after a certain time the mockups will be generated, so you will have to check frequently if the task is done. First request for result should not be sooner than 10 seconds. So plan ahead that the generation task will be done in two steps - creating a task and the checking with intervals if the task is ready.

Important! URLs to mockup images are temporary, they will expire after a day, so you have to store them on your own server.

Process flow

  1. Decide which product variants you want to generate.

  2. Retrieve the list of print files for chosen product and variants. Use the variant print file mappings to determine which print file you need to generate for a specific placement on a specific product's variant.

  3. Upload your file to a public URL that matches the print file size ratio (or provide positions for the generation request)

  4. Create a mockup generation task and store the task key.

  5. Use the task key to check if task is completed. If still pending, repeat after an interval.

  6. When the task is done, download and store mockups on your own server. Mockup URLs are temporary and will be removed after a day.

Usage example

Let's take an example. You want to offer users to design their own t-shirt.

We'll pick this shirt as an example - Bella + Canvas 3001 Unisex T-shirt

Its product id is 71.

Let's fetch some variants available for this shirt:
https://api.printful.com/products/71

We'll choose white and black shirt in M, L, XL sizes. Respective variant ids:
4012, 4013, 4014, 4017, 4018 and 4019.

Next, we need to get the print file sizes for these variants:
https://api.printful.com/mockup-generator/printfiles/71

We see that there are two placements available for this product - front and back. Posters, for example, will only have one placement called default.

By looking up our picked variant ids, we see that they all use same print file for back and front prints:

{
    product_id: 71,
    available_placements: {
        front: "Front print",
        back: "Back print",
        label_outside: "Outside label"
    },
    printfiles: [
        {
            printfile_id: 1,
            width: 1800,
            height: 2400,
            dpi: 150, // For given width and height, this is the resulting DPI on the actual product.
            fill_mode: "fit", // Possible values: "fit" or "cover". Indicates in what mode mockups will be generated.
            can_rotate: false // Posters for example, allow rotation. If you pass image in horizontal positions.
        }
    ],
    …
    variant_printfiles: [
        {
            variant_id: 4012,
            placements: {
                front: 1, // printfile id
                back: 1
            }
        }
        …
    ],
    …
}

We can see that the full print file size is 1800×2400 for back and front prints for chosen variants.

Important - this is the print file size we use for printing. For mockup generation your image should not exceed width of 1000px, because resulting mockups won't be larger than 1000px.

When we know the size of the print file, we need to calculate the positions. Position values are relative here, image size does not have to match the width and height of positions. When mockup is generated we will fit position area inside the print area or will cover it, depending on print file fill_mode value.

Positions given below would result in a square image centered vertically within the print area.

    {
        area_width: 1800, // Relative width of the print area
        area_height: 2400, // Relative height of the print area
        width: 1800, // Relative width of your image
        height: 1800, // Relative height of your image
        top: 300, // Relative image top offset within the area
        left: 0 // Relative image left offset within the area
    }

Important - for posters, canvas and other products which print files allow rotation (can_rotate value in print file response) you can flip width and height to create a product mockup that is horizontal or vertical.

Once we have calculated the positions, we can perform the actual mockup generation using the mockup generator endpoint:

POST to https://api.printful.com/mockup-generator/create-task/71 with body parameters:

{
    variant_ids : [4012, 4013, 4014, 4017, 4018, 4019],
    format: 'jpg',
    files : [
        {
            placement: 'front',
            image_url: 'http://your-site/path-to-front-printfile.jpg',
            position: {
                area_width: 1800,
                area_height: 2400,
                width: 1800,
                height: 1800,
                top: 300,
                left: 0
            }
        },
        {
            placement: 'back',
            image_url: 'http://your-site/path-to-back-printfile.jpg',
            position: {
                area_width: 1800,
                area_height: 2400,
                width: 1800,
                height: 1800,
                top: 300,
                left: 0
            }
        },
    ],
}

In response, you will receive task key and current task status:

{
    task_key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    status: "pending"
}

After an interval of a few seconds, you can try to check for the result by calling a GET request on https://api.printful.com/mockup-generator/task?task_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

If the task is completed, the response will be like this:

{
    task_key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    status: "completed",
    mockups: [
        {
            variant_ids: [
                4011,
                4012,
                4013
            ],
            placement: "front",
            mockup_url: "https://url-to/front-mockup.png"
        },
        {
            variant_ids: [
                4011,
                4012,
                4013
            ],
            placement: "back",
            mockup_url: "https://url-to/back-mockup.png"
        },
        {
            variant_ids: [
                4016,
                4017,
                4018
            ],
            placement: "front",
            mockup_url: "https://url-to/front-mockup.png"
        },
        {
            variant_ids: [
                4016,
                4017,
                4018
            ],
            placement: "back",
            mockup_url: "https://url-to/back-mockup.png"
        }
    ]
}

At this point, you just have to download the mockup URLs and store them on your own server and you're good to go!

Product templates

If you wish to build your own mockup generator UI, this is the place to start. Using the product template endpoint you can get template images and positions necessary to create a tool where your users can position their files on.

If you want to create a mug generator, for example, you call the endpoint /mockup-generator/templates/19 with mug product ID. By looking at the variant mapping field, we can determine that for variant 1320 11oz mug we have to use template with ID 919. This is what template structure looks like:

{
    template_id: 919,
    image_url: "https://www.printful.com/files/generator/40/11oz_template.png",
    background_url: null,
    background_color: null,
    printfile_id: 43, // We can retrieve the actual printfile size from printfiles endpoint
    template_width: 560, // This is the main container width, pixels
    template_height: 295, // Main container height
    print_area_width: 520, // Inner area where positioning happens
    print_area_height: 202, // Inner area
    print_area_top: 18, // Offset from the main container
    print_area_left: 20, // Offset from the main container
    is_template_on_front: true // This indicates if we should show user image below or above the template image
}

Given this information, we can create a simple HTML markup:

<div style="position: relative; width: 520px; height: 295px;">
    <div style="position: absolute; width: 520px; height: 202px; top:18px; left:20px; background:rgba(255,233,230,0.33)">
        <img src="/static/images/layout/logo-printful.png" style="position: absolute; left: 43px; top: 77px; width: 140px; height: 63px;">
    </div>
    <div style="position: absolute; width: 560px; height: 295px; background:url(/files/generator/40/11oz_template.png) center center no-repeat"></div>
</div>

Which would look like this in the browser:

To generate mockups with positions above, we perform a POST request to https://api.printful.com/mockup-generator/create-task/19 with body parameters:

{
    variant_ids : [1320],
    format: 'jpg',
    files : [
        {
            placement: 'default',
            image_url: 'https://duw6wk4ou1qt.cloudfront.net/static/v626/images/layout/logo-printful.png',
            position: {
                area_width: 520, // Value of print_area_width in the template
                area_height: 202, // Value of print_area_height in the template
                width: 140, // Image width
                height: 63, // Image height
                top: 77, // Image top offset in area
                left: 43 // Image left offset in area
            }
        }
    ]
}

Endpoints

Create a mockup generation task

POST https://api.printful.com/mockup-generator/create-task/{id}

Creates an asynchronous mockup generation task. Generation result can be retrieved using mockup generation task retrieval endpoint.
Input parameters:
id integer Product ID.
Request body CreateGenerationTask Mockup generation data.
variant_ids integer [ ] List of variant ids you want to generate.
format {jpg, png} Generated file format. PNG will have a transparent background, JPG will have a smaller file size.
option_groups string [ ] Option groups you want to generate. Available list is to be found in printfile API request.
options string [ ] Options you want to generate. Available list is to be found in printfile API request.
files GenerationTaskFile [ ] Placement and file mapping to be generated.
placement string Placement identifier (front, back, etc.).
image_url string Public URL where your file is stored.
position GenerationTaskFilePosition Position
area_width integer Positioning area width on print area
area_height integer Positioning area height on print area
width integer Width of the image in given area
height integer Height of the image in given area
top integer Image top offset in given area
left integer Image left offset in given area
Response format:
code integer Response status code 200
result GenerationTask
task_key string Task identifier you will use to retrieve generated mockups.
status {pending, completed, failed} Status of the generation task.
error string If task has failed, reason will be provided here.
mockups GenerationTaskMockups [ ] If task is completed, list of mockups will be provided here.
placement string Placement identifier.
variant_ids integer [ ] List of variant ids this mockup is used for. One mockup can be used for multiple variants.
mockup_url string Temporary URL of the primary mockup.
extra GenerationTaskExtraMockup [ ] Optional extra mockups.
title string Display name of the extra mockup.
url string Temporary URL of the mockup.
API key
id Product ID.
Request body
Execute

Retrieve product variant printfiles

GET https://api.printful.com/mockup-generator/printfiles/{id}

List of printfiles available for products variants. Printfile indicates what file resolution should be used to create a mockup or submit an order.
Input parameters:
id integer Product ID
Response format:
code integer Response status code 200
result PrintfileInfo
product_id integer Requested product id.
available_placements object List of available placements. Key is placement identifier, value is display name. (e.g. {embroidery_front: Front, ..}).
printfiles Printfile [ ] Array of printfiles available for product.
printfile_id integer Unique printfile identifier.
width integer Width in pixels.
height integer Height in pixels.
dpi integer Resulting DPI for given width and height.
fill_mode {cover, fit} Indicates if printfile will be used in cover or fit mode. Cover mode can produce cropping if side ratio does not match printfile.
can_rotate boolean Indicates if printfile can be rotated horizontally (e.g. for posters).
variant_printfiles VariantPrintfile [ ] Each variant mapping to placement and their printfiles.
variant_id integer Product variant id.
placements object Key is placement and value is representing printfile_id. (e.g. {front: 1, back: 2, ..}).
option_groups string [ ] List of option groups available (e.g. for leggings Barefoot, High-heels, etc.). Note that not every variant has all groups available for generation.
options string [ ] List of options available for generation (e.g. Front, Back).
API key
id Product ID
Execute

Mockup generation task result

GET https://api.printful.com/mockup-generator/task

Returns asynchronous mockup generation task result. If generation task is completed, it will contain a list of generated mockups.
Input parameters:
task_key string Task key retrieved when creating the generation task.
Response format:
code integer Response status code 200
result GenerationTask
task_key string Task identifier you will use to retrieve generated mockups.
status {pending, completed, failed} Status of the generation task.
error string If task has failed, reason will be provided here.
mockups GenerationTaskMockups [ ] If task is completed, list of mockups will be provided here.
placement string Placement identifier.
variant_ids integer [ ] List of variant ids this mockup is used for. One mockup can be used for multiple variants.
mockup_url string Temporary URL of the primary mockup.
extra GenerationTaskExtraMockup [ ] Optional extra mockups.
title string Display name of the extra mockup.
url string Temporary URL of the mockup.
API key
task_key Task key retrieved when creating the generation task.
Execute

Product templates

GET https://api.printful.com/mockup-generator/templates/{id}

Retrieve list of templates that can be used for client-side positioning.
Input parameters:
id int Product ID.
Response format:
code integer Response status code 200
result ProductTemplates
version integer Resource version. If this changes, resources (positions, images, etc.) should be re-cached.
min_dpi integer Recommended minimum DPI for given product.
variant_mapping TemplateVariantMapping [ ] List of product variants mapped to templates. From this information you can determine which template should be used for a variant.
variant_id integer Product variant ID.
templates TemplateVariantMappingItem [ ] Product variant ID.
placement string Placement ID.
template_id integer Corresponding template id which should be used for this variant and placement combination.
templates Template [ ] List of templates. Use variant_mapping to determine which template corresponds to which product variant.
template_id integer Template ID.
image_url string Main template image URL.
background_url string Background image URL (optional).
background_color string HEX color code that should be used as a background color.
printfile_id integer Printfile ID that should be generated for this template. See printfile API endpoint for list of Printfiles.
template_width integer Width of the whole template in pixels.
template_height integer Height of the whole template in pixels.
print_area_width integer Print area width (image is positioned in this area).
print_area_height integer Print area height (image is positioned in this area).
print_area_top integer Print area top offset (offset in template).
print_area_left integer Print area left offset (offset in template).
is_template_on_front boolean Should the main template image (image_url) be used as an overlay or as a background.
conflicting_placements TemplatePlacementConflict [ ] List of conflicting placements. Used to determine which placements can be used together.
placement string Placement ID
conflicts string [ ] List Placement IDs that are conflicting with given placement
API key
id Product ID.
Execute

Ready to try Printful ?

Get Me Started