Language: EN
Start free

Herofab images on Shopify products

Three small Node.js files connect a Shopify store to the Herofab API: one starts a Herofab job for each product from the product's own main image, another receives Herofab's signed webhook and adds the finished image to the same product through Shopify's Admin GraphQL API, version 2026-10.

  • Node.js 20+
  • Shopify Admin GraphQL 2026-10
  • Signed webhooks
Before you start

What you need

  1. A Herofab API key with the jobs:read, jobs:write and webhooks:write scopes, created by the workspace owner in the app.
  2. A Shopify Admin API access token for your store with the write_products scope, from an app you create for the store.
  3. A public HTTPS address for receive.mjs, registered as a Herofab webhook endpoint for job.succeeded; keep the whsec_ secret it returns.
  4. verify.mjs: the Node.js signature check from the Herofab webhooks page.
Step 1

A helper for Admin GraphQL calls

Every call goes to the versioned endpoint with the X-Shopify-Access-Token header; GraphQL errors stop the script.

// shopify.mjs — one Admin GraphQL call (API version 2026-10).
const ADMIN = `https://${process.env.SHOPIFY_SHOP}/admin/api/2026-10/graphql.json`;   // your-store.myshopify.com

export async function shopify(query, variables = {}) {
  const res = await fetch(ADMIN, {
    method: "POST",
    headers: { "X-Shopify-Access-Token": process.env.SHOPIFY_TOKEN, "Content-Type": "application/json" },
    body: JSON.stringify({ query, variables }),
  });
  const { data, errors } = await res.json();
  if (errors) throw new Error(JSON.stringify(errors));
  return data;
}
Step 2

Start a Herofab job for each product

POST /api/v1/assets with a url makes Herofab fetch the product image once. Herofab jobs carry no metadata of yours, so the script writes job id → product to jobs.json for the receiver.

// start.mjs — Node 20+. For each active product: import its main image into Herofab and start a job.
import fs from "node:fs";
import { shopify } from "./shopify.mjs";

const HEROFAB = "https://app.herofab.app/api/v1";
const herofab = { Authorization: `Bearer ${process.env.HEROFAB_API_KEY}`, "Content-Type": "application/json" };

const { products } = await shopify(`{
  products(first: 20, query: "status:active") {
    nodes { id title featuredMedia { preview { image { url } } } }
  }
}`);
const jobs = fs.existsSync("jobs.json") ? JSON.parse(fs.readFileSync("jobs.json", "utf8")) : {};
for (const product of products.nodes) {
  const url = product.featuredMedia?.preview?.image?.url;
  if (!url) continue;
  // Herofab fetches the image once and keeps it as an asset.
  const asset = await (await fetch(`${HEROFAB}/assets`, { method: "POST", headers: herofab, body: JSON.stringify({ url }) })).json();
  if (asset.state !== "stored") continue;
  const id = product.id.split("/").pop();
  const job = await (await fetch(`${HEROFAB}/jobs`, {
    method: "POST",
    // The same product and tool give the same key: running the script twice does not pay twice.
    headers: { ...herofab, "Idempotency-Key": `shopify-${id}-product_studio` },
    body: JSON.stringify({ tool: "product_studio", inputs: { product: asset.id },
      params: { scene: "studio_white", shadow: "soft", marketplace: "shopify" } }),
  })).json();
  jobs[job.id] = { product: product.id, title: product.title };
}
fs.writeFileSync("jobs.json", JSON.stringify(jobs, null, 1));
Step 3

Receive the webhook and add the image

The image bytes are uploaded to a Shopify staged upload target (resource IMAGE, PUT with the returned parameters as headers), then attached with productUpdate and its media argument, which adds media without replacing the product's other images.

// receive.mjs — Node 20+. Herofab calls this when a job ends; the image is added to the product.
import http from "node:http";
import fs from "node:fs";
import { verify } from "./verify.mjs";       // the Node.js function on the webhooks page
import { shopify } from "./shopify.mjs";

const HEROFAB = "https://app.herofab.app/api/v1";
const auth = { Authorization: `Bearer ${process.env.HEROFAB_API_KEY}` };
const seen = new Set();

async function addImage(productGid, output, alt) {
  // 1. The result's bytes (the content URL answers with a short-lived link)
  const bytes = Buffer.from(await (await fetch(`${HEROFAB}/assets/${output.asset_id}/content`, { headers: auth })).arrayBuffer());
  // 2. A staged upload target on Shopify (resource IMAGE)
  const { stagedUploadsCreate } = await shopify(`mutation ($input: [StagedUploadInput!]!) {
    stagedUploadsCreate(input: $input) { stagedTargets { url resourceUrl parameters { name value } } userErrors { field message } }
  }`, { input: [{ filename: `herofab-${output.asset_id}.${output.content_type.split("/")[1]}`, mimeType: output.content_type, resource: "IMAGE", httpMethod: "PUT" }] });
  const [target] = stagedUploadsCreate.stagedTargets;
  // 3. PUT the bytes; the returned parameters travel as headers
  await fetch(target.url, { method: "PUT", headers: Object.fromEntries(target.parameters.map((p) => [p.name, p.value])), body: bytes });
  // 4. Add it to the product: media only adds, it never replaces existing images
  const { productUpdate } = await shopify(`mutation ($product: ProductUpdateInput!, $media: [CreateMediaInput!]) {
    productUpdate(product: $product, media: $media) { product { id } userErrors { field message } }
  }`, { product: { id: productGid }, media: [{ originalSource: target.resourceUrl, mediaContentType: "IMAGE", alt }] });
  if (productUpdate.userErrors.length) throw new Error(JSON.stringify(productUpdate.userErrors));
}

http.createServer(async (req, res) => {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  const raw = Buffer.concat(chunks).toString("utf8");
  if (!verify(process.env.HEROFAB_WEBHOOK_SECRET, req.headers, raw)) return res.writeHead(401).end();
  res.writeHead(200).end();                    // answer within 10 seconds, then do the work
  const event = JSON.parse(raw);
  if (event.type !== "job.succeeded" || seen.has(event.id)) return;   // retries reuse the same id
  seen.add(event.id);
  const target = JSON.parse(fs.readFileSync("jobs.json", "utf8"))[event.data.job.id];
  if (!target) return;
  const job = await (await fetch(`${HEROFAB}/jobs/${event.data.job.id}`, { headers: auth })).json();
  await addImage(target.product, job.outputs[0], target.title);
}).listen(8080);
Limits

Shopify facts this recipe relies on

ItemShopify documentation
API version2026-10 is the latest stable Admin API version; productCreateMedia is deprecated in favour of productUpdate or productSet
Staged uploadsstagedUploadsCreate returns url, resourceUrl and parameters; images are sent with PUT and the parameters as headers
Adding mediaproductUpdate(product, media) adds new media; productSet replaces list fields, so it can delete images that are not in the request
Access scopeproductUpdate requires write_products
Image limitsUp to 20 MB and 4472 × 4472 px (20 megapixels); PNG, GIF, JPEG, WEBP or HEIC

shopify.dev — stagedUploadsCreate · shopify.dev — productUpdate · shopify.dev — Manage media · shopify.dev — API versioning · checked 30 October 2026

Questions

Shopify recipe questions

Why not give Shopify the Herofab image URL directly?

The download link of a Herofab result is short-lived and needs your API key to obtain. The staged upload puts the bytes on Shopify's own storage first, which Shopify's media guide recommends for files that are not at a public URL.

Does the new image replace the product's main image?

No. productUpdate with media adds the image to the product's media; reorder or remove images in the Shopify admin or with Shopify's media mutations.

Which Herofab tool fits a Shopify store?

The recipe uses the product studio on a white backdrop with marketplace "shopify", which fits the image to 2,048 × 2,048 px. Virtual try-on or ghost mannequin work the same way with their own input role and settings.

Related
Get started

Your next collection, shot this week.

20 credits at sign-up, no card required. Images made with free credits carry a watermark. Herofab also removes the watermark from those images once credits are purchased.