Mockup generator REST API

All requests use Bearer tokens. Supply your pk_ API key in the Authorization header: Authorization: Bearer pk_.... pk_ keys identify the shop and act as the credential for uploads, job creation, and retrieving outputs. Rotate keys from the dashboard and limit access by creating separate keys per integration.

Keep the key secret. Use server-side calls for production jobs. Client-side keys are acceptable only for temporary staging flows behind a proxy or signed upload URLs.

POST /v1/mockup creates a mockup job. The payload includes your shop identifier, a userSetId (optional), source asset references or upload URLs, and a mockup profile. Include a callback URL if you want webhook callbacks. The endpoint accepts PSDs with smart objects and print files at 300 DPI.

Responses are JSON. Expect a jobId, status (queued, processing, finished, failed), userSetId, mockupSetId, and an outputs array. Each output contains type (image, video, pdf), url, width, height, dpi, and ratio. Wall art jobs include a driveShareLink and listingPdf in outputs when complete.

A userSetId groups assets, presets, and generated outputs. Create a userSetId on the first job or via the mockup-set endpoints (/v1/mockup-sets). Reuse that userSetId to update assets, swap PSD smart objects, or push new sizes without reconfiguring build settings.

Mockup-set endpoints let you list, update, and delete sets. Use them to manage versioning, update a PSD template across many listings, and track which listings reference a shared set. This is the production layer for repeatable listings.

Send batches or single jobs. Clipart batches support 1–50 images per job. For high parallel throughput, fan out individual POST /v1/mockup calls per listing. Respect rate limits and stagger uploads to avoid spikes.

Polling works for low volume: poll the jobId until status changes. Webhooks are recommended for production: include a callback URL on job creation and receive an immediate POST on completion. Webhooks include retry headers and idempotency keys; poll only as a fallback.

Ratio Ready uses PSD smart objects as placeholders. Name smart objects consistently and export them at the intended print DPI. Wall art jobs produce 5 print sizes at 300 DPI (2:3, 3:4, 4:5, 11:14, ISO A1). Poster jobs generate a single 300 DPI print file and require a shipping profile when listed on Etsy.

Clipart batches return print-ready files at 300 DPI and listing previews. Provide layered PSDs where assets replace a single smart object slot for predictable results.

Use the free Make.com blueprint included with your account. It runs on the free Make.com tier (1,000 ops/month ≈ 80–125 listings/month). The REST API also works with n8n, Zapier, or custom webhooks and code.

One-time setup for the Make.com blueprint is 30–45 minutes. Per-listing interaction is ~2 minutes to upload and configure, then 3–5 minutes processing. Accounts get 75 free credits on signup. Wall art jobs cost 59 credits, posters 55 credits, and clipart batches start at 29 credits (+10 credits per extra 5 images). Pricing supports usage; engineering teams budget credits per listing.