Mockups

Merchrocket's Mockup Generator API allows you to create realistic product mockups for your products. This API is designed to help you visualize how your designs will look on various merchandise items offered by Merchrocket.

Due to the resource-intensive nature of this operation, we process requests asynchronously. This means you won't receive the results immediately. Instead, you will get a task ID, which you can use to retrieve the mockups once they are ready using the Retrieve mockup generator tasks endpoint. Additionally, you can subscribe to the Mockup generator task finished webhook event to be notified when the processing is complete.

Four details are required to create a mockup task:

catalogProductId- The id of the catalogProduct. You could retrieve a list of products here. This property is optional and only needs to be specified if all variants are to be generated, and you do not want to specify all variant IDs
catalogVariantIds- If you do not want to create the mockups for all variants of the product, but only for certain variants, then enter the variant IDs of the desired variants here. You can find a list of the variants here.
url- The url to the image to be placed on the product. The dimensions should correspond to the aspect ratio of the product placement area. The placement area can be found in the CatalogVariant endpoint.
type - The type of the placement area. A product can be personalised in several places. In the following example of a mug on the left and right of the handle. It is therefore necessary to specify which area is involved in the placement area.

To illustrate the procedure, we have provided an example here using a double-sided mug.

An image

As you can see in the picture, there is one placement area to the left of the handle and one to the right. So let's take a look at the definition of the placements that we have retrieved via the CatalogVariant endpoint.

json

  ...
  "placements": [
    {
      "type": "left",
      "technique": "direct_print",
      "area": {
        "width": 85,
        "height": 80,
        "section": {"top": 0, "right": 0, "bottom": 0, "left": 0}
      }
    },
    {
      "type": "right",
      "technique": "direct_print",
      "area": {
        "width": 85,
        "height": 80,
        "section": {"top": 0, "right": 0, "bottom": 0, "left": 0}
      }
    }
  ]

From this we can see that there are two placements for the product variant. These two placements must also be specified when creating a mockup task. An example payload for the MockupTask call could then look like this. You can find even more detailed examples in the Examples → Mockups → Simple section.

json

// Example MockupTask creation payload
{
  "format": "jpeg",
  "requestedProducts": [
    {
      "catalogProductId": "952b416d-499b-4399-87d2-6a84a4c898c0",
      "catalogVariantIds": ["69b54822-e007-49ea-a1fe-3d64906da8e2"],
      "placements": [
        {
          "layers": [
            {
              "url": "https://d3r2wt7l0tcdny.cloudfront.net/products/mug_heart/print_source.jpg",
              "type": "file"
            }
          ],
          "technique": "direct_print",
          "type": "left"
        },
        {
          "layers": [
            {
              "url": "https://d3r2wt7l0tcdny.cloudfront.net/products/mug_heart/print_source.jpg",
              "type": "file"
            }
          ],
          "technique": "direct_print",
          "type": "right"
        }
      ]
    }
  ]
}

As a result, the MockupTask identifier (id) is returned in order to finally retrieve the created images via the MockupTask Info Endpoint.

json

// Example MockupTask info result (status > pending)
{
  "@context": "/api/contexts/MockupTask",
  "@id": "/api/mockup-tasks/01903584-7c78-7592-b0bc-6df076e02957",
  "@type": "MockupTask",
  "id": "01903584-7c78-7592-b0bc-6df076e02957",
  "status": "pending",
  "catalogVariantMockups": [],
  "failureReasons": [],
  "createdAt": "2024-06-20T11:59:53+00:00",
  "finishedAt": null
}

As the creation of the mockup images can take a little longer depending on the complexity of the product and the number of images, this process is asynchronous, so you have to wait a little while for the result. However, you can also be notified via the webhook when the creation of the images is complete. The result would then look like this.

json

// Example MockupTask info result (status > completed)
{
"@context": "/api/contexts/MockupTask",
"@id": "/api/mockup-tasks/01903584-7c78-7592-b0bc-6df076e02957",
"@type": "MockupTask",
"id": "01903584-7c78-7592-b0bc-6df076e02957",
"status": "completed",
"catalogVariantMockups": [
    {
        "@type": "CatalogVariantMockup",
        "@id": "/api/.well-known/genid/97a46196ff04455eb61f",
        "catalogVariantId": "69b54822-e007-49ea-a1fe-3d64906da8e2",
        "mockups": [
            {
            "@type": "Mockup",
            "@id": "/api/.well-known/genid/9f4107faefc5300cc75c",
            "placement": "main",
            "displayName": "mockup-1",
            "technique": "direct_print",
            "mockupUrl": "https://dbcq9of27g5zl.cloudfront.net/mockup_mug_beidseitig_all_colors-mockup-1-b65659b2b9c9541a871ba9dfdd49a8bc944599c3.jpg"
            },
            {
            "@type": "Mockup",
            "@id": "/api/.well-known/genid/341d82e5adaa79a2fcfd",
            "placement": "main",
            "displayName": "mockup-2",
            "technique": "direct_print",
            "mockupUrl": "https://dbcq9of27g5zl.cloudfront.net/mockup_mug_beidseitig_all_colors-mockup-2-b65659b2b9c9541a871ba9dfdd49a8bc944599c3.jpg"
            },
            {
            "@type": "Mockup",
            "@id": "/api/.well-known/genid/ac88a37edec78cda6ba5",
            "placement": "main",
            "displayName": "mockup-3",
            "technique": "direct_print",
            "mockupUrl": "https://dbcq9of27g5zl.cloudfront.net/mockup_mug_beidseitig_all_colors-mockup-3-b65659b2b9c9541a871ba9dfdd49a8bc944599c3.jpg"
            }
      ]
    }
],
"failureReasons": [],
"createdAt": "2024-06-20T11:59:53+00:00",
"finishedAt": "2024-06-20T11:59:54+00:00"
}

If something goes wrong or the information provided when creating the MockupTask is incorrect, the info result will contain one or more reasons why the task was not created.

json

// Example MockupTask info result (status > failed)
{
  "@context": "/api/contexts/MockupTask",
  "@id": "/api/mockup-tasks/01903599-b5b3-7ca6-a7dc-802e41901ce0",
  "@type": "MockupTask",
  "id": "01903599-b5b3-7ca6-a7dc-802e41901ce0",
  "status": "failed",
  "catalogVariantMockups": [],
  "failureReasons": [
    {
      "@type": "FailureReason",
      "@id": "/api/.well-known/genid/e8233ed34cdcf036569c",
      "type": "exception",
      "detail": "The product variant [69b54822-e007-49ea-a1fe-3d64906da8e2] needs a placement with type [left]. This placement could not be found in your requested product placement."
    }
  ],
  "createdAt": "2024-06-20T12:23:04+00:00",
  "finishedAt": "2024-06-20T12:23:05+00:00"
}

Mockups ​

Mockups