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
What you need
- A Herofab API key with the jobs:read, jobs:write and webhooks:write scopes, created by the workspace owner in the app.
- A Shopify Admin API access token for your store with the write_products scope, from an app you create for the store.
- A public HTTPS address for receive.mjs, registered as a Herofab webhook endpoint for job.succeeded; keep the whsec_ secret it returns.
- verify.mjs: the Node.js signature check from the Herofab webhooks page.
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;
}
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));
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);
Shopify facts this recipe relies on
| Item | Shopify documentation |
|---|---|
| API version | 2026-10 is the latest stable Admin API version; productCreateMedia is deprecated in favour of productUpdate or productSet |
| Staged uploads | stagedUploadsCreate returns url, resourceUrl and parameters; images are sent with PUT and the parameters as headers |
| Adding media | productUpdate(product, media) adds new media; productSet replaces list fields, so it can delete images that are not in the request |
| Access scope | productUpdate requires write_products |
| Image limits | Up 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
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.
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.