Help & Setup

← Back to the app ⬇ Download Setup Guide (PDF)

⚡ Quick start

  1. Create a free account (Sign Up) and log in.
  2. Drag & drop your artwork — the aspect ratio is detected automatically.
  3. Pick mockup scenes from the template browser (only scenes whose frames fit your art are highlighted).
  4. Hit Generate for mockup images, or use a Full Package (below) for everything at once.

Fine-tune any result with Adjust Mockup: art brightness/contrast preview live inside the frame; scene sliders adjust the room around it.

📦 Full packages

The purple Generate Full Package button produces one ZIP per artwork containing:

DPI choice

300 DPI is standard print quality but most files exceed Etsy's 20MB upload cap (fine when Dropbox hosts your bundle). 150 DPI keeps every file under the cap for direct Etsy attachment.

Package ZIPs download automatically when generation finishes; your print files are also cached on the Deliverables page per your plan's retention.

⚡ Bulk Mockup Generator

The orange button next to the app title runs the whole seller flow hands-off:

  1. Select multiple artwork files.
  2. Step through mockup categories — use all, none, or hand-pick thumbnails. Generate & Push to Etsy is available at every step.
  3. Each image automatically uses only the selected scenes that fit its aspect ratio.
  4. Per image: package + AI listing generated → full bundle uploaded to your Dropbox (if connected) → Etsy draft listing created.

When it finishes you get links to your Deliverables and your Etsy drafts. Nothing goes live until you activate a draft in Etsy.

Etsy free

Publishes packages as draft listings in your shop: mockups become the photos, print files attach as the digital product, AI text fills title/description/tags.

Quickest path: generate mockups, edit them to taste, then hit the orange 🏪 Etsy button on any card — every mockup of that artwork joins the same listing as photos (the clicked card is the cover, max 10), the AI describes it, print files attach, and one draft appears in your shop.

One-time setup

  1. Apply for an API app at etsy.com/developers (a personal app for your own shop is approved fastest).
  2. On the app page, note the Keystring and the Shared Secret — you need both.
  3. In the app's settings add the callback URL — it follows wherever the app runs: <your-app-url>/etsy/callback. For local testing that is http://localhost:8000/etsy/callback; when deployed, add your production URL (e.g. https://yourdomain.com/etsy/callback) as well — multiple URLs can be registered at once. Use the Callback URL(s) field, not "Application URL".
  4. In Mockup Generator: user menu → Integrations → Etsy → paste both values → Save Keys.
  5. Click Connect Etsy Shop → authorize on Etsy → wait for the ✓ page.

Where things land

Drafts: Shop Manager → Listings → Drafts. Review and activate there (Etsy charges its $0.20 listing fee on activation, not on draft creation).

Dropbox free

Etsy caps digital files at 5 files × 20MB. With Dropbox connected, every published listing gets its own private full-resolution bundle uploaded to your Dropbox (Apps/<app>/Etsy Bundles/), and buyers receive the download link in a PDF attached to the listing.

Dropbox hosting is pre-configured by the Scenehatch team — if the Connect button says "not available", contact support.

No Dropbox? Delivering the full bundle manually

Without Dropbox connected, publishing still attaches every print file that fits Etsy's limits (5 files, 20MB each — generate at 150 DPI and usually all of them fit). To also deliver the full high-resolution bundle by hand:

  1. Get your files. The package ZIP downloads automatically when generation finishes; print files are also kept on the Deliverables page. Unzip it — the deliverables/ folder holds every size.
  2. Host them on any cloud storage. For example Google Drive: drive.google.com → New → Folder upload → after upload, right-click the folder → Share → change access to "Anyone with the link" → Copy link. (Dropbox's website, OneDrive or similar work the same way.)
  3. Make a link document for buyers. Create a one-page PDF in any word processor: "Thank you for your purchase — download your full-resolution files here: [paste link]", plus a line that no account is needed. Export/print it as PDF.
  4. Attach it on Etsy. Shop Manager → Listings → Drafts → open your listing → Digital files → upload the PDF alongside the attached print files → Save.
  5. Test like a buyer. Open your link in a private/incognito window — it must download without asking you to log in.
  6. Keep the link alive for as long as the listing sells; deleting the hosted files breaks past buyers' downloads.

Connecting your account

  1. User menu → Integrations → Dropbox → Connect Dropbox.
  2. Authorize on the Dropbox page → ✓ page → done.

From then on it's automatic: leave the "download link" prompt empty when publishing and the bundle uploads itself. Pasting a link manually always overrides. Mind your Dropbox storage quota — bundles run 50–500MB each.

Buyer access: the generated links are "anyone with the link" — buyers need no Dropbox account. The links are unguessable, so nobody can browse your other bundles. Exception: on Dropbox Business/team accounts an admin policy can restrict links to team members, which breaks buyer downloads — personal accounts are unaffected.

Google Drive free

The alternative to Dropbox for hosting full-resolution bundles — with a much roomier 15GB free tier (Dropbox: 2GB). When Dropbox isn't connected, published listings upload their bundle to your Google Drive instead and buyers get the download link the same way. The app uses Google's most restrictive Drive permission (drive.file): it can only see the "Etsy Bundles" folder it creates itself — never your other files, photos or documents.

Important: being logged into Google in your browser does not connect Google Drive to this app. The connection only exists after you click Connect Google Drive in Integrations and complete Google's consent screen — and that button only works after the one-time app registration below.

Google Drive support is pre-configured by the Scenehatch team.

For sellers (everyone who isn't the operator)

You never touch Google Cloud or .env — the walkthrough above is done once by whoever runs the server. Your part is two clicks: user menu → Integrations → Connect Google Drive → choose your Google account → Allow. Done — bundles upload to your own Drive automatically when you publish. (While the platform's Google app is unverified, your Gmail must be on the operator's test-user list — ask them to add you if Google shows "access_denied".)

How it's used

Printify free

Sell physical canvas prints: one click creates a Printify product with the popular sizes matching your art's aspect ratio, retail prices set automatically from print cost + your profit margin (default 30% after Etsy fees; change with PRINT_PROFIT_MARGIN in .env). Low-resolution art is auto-upscaled to 300 DPI, and sizes that would still print below 250 DPI are dropped.

One-time setup

  1. Connect your Etsy shop to Printify first (needed for publishing): Printify → Manage my stores → Add new store → Etsy → authorize. If Printify says the Etsy shop is "already linked to your Printify store", the link lives in another Printify account or a disconnected store — use Reconnect on the existing store, or revoke Printify from Etsy (Shop Manager → Settings → Integrations) and connect again.
  2. Get a token from the SAME Printify account that owns the Etsy-connected store: avatar (top right) → Connections → API → Generate. A token from a different Printify account cannot see this store — the classic symptom is "shop is not connected to sales channel" errors even though the dashboard shows it connected.
  3. Integrations → Printify → paste the token (Shop ID optional — the Etsy-connected shop is picked automatically) → Connect Printify.

After each push — adding your room mockups

Printify products start with its default flat previews. To use your generated room mockups as the listing photos:

  1. In the success dialog, click ⬇ Save the mockups to download them.
  2. Open the Mockup Library link for the product.
  3. Click My Uploads → upload the mockup images (max 15).
  4. Click Save, then Save selection to attach them to the product.

Products are created as drafts in Printify; publish from there when photos and prices look right. Publishing creates a separate physical Etsy listing (Etsy can't mix digital and physical in one listing) and Etsy's $0.20 listing fee applies. If a freshly published listing lands as inactive/archived on Etsy, activate it in Shop Manager → Listings.

Canvas side printing defaults to off (white edges); set PRINTIFY_PRINT_ON_SIDE=regular in .env for wrap-around art.

Printful free

Same idea as Printify, on Printful's catalog.

One-time setup

  1. Create an API store. Go to printful.com/dashboard/store → click "Connect via API" → name your store. (Printful's API can only create products in API-platform stores — marketplace-connected stores like Etsy or Shopify are rejected.)
  2. Create a token. On the developer site (developers.printful.com) open the Tokens page → fill in a token name and expiration date → set access level to "Account (all stores)" → tick all scopes → create, then copy the API key (and note the store ID).
    Access level matters: a token scoped to a single marketplace store cannot see your API store. "Account (all stores)" avoids that trap. If any form asks for an app/redirect URL, your shop URL or app URL works — it is not used by this integration.
  3. Connect. Integrations → Printful → paste the API key (Store ID optional — the API store is picked automatically over marketplace stores) → Connect Printful.
Printful downloads print files from this server by URL, so pushes only complete when the app runs on a publicly reachable URL — on localhost the product is created but the file fetch fails.

Instagram free

Posts mockups directly to an Instagram Business/Creator account via the 📸 Gram button on result cards — AI-written caption ending with your Etsy link. Uses Meta's "Instagram API with Instagram login": no Facebook Page required.

For sellers — connecting your account (2 clicks)

You never touch Meta's developer console or any server files — the walkthrough below is done once by whoever runs the server. Your part: user menu → Integrations → Social promotion → Instagram → Connect → log in with your Instagram Business/Creator account → Allow. While the platform's Meta app is unverified, your IG account must be on the operator's tester list — ask them to add you if the connect is refused.

Instagram support is pre-configured by the Scenehatch team. If your connect is refused, ask support to add your IG account to the tester list.

Requirements & behaviour

📣 Social promotion free

After a listing is on Etsy, the purple 📣 Promote button on its result cards posts the mockup with an AI-written advertising blurb to every connected platform at once — each post linking to the Etsy listing to funnel buyers there.

Connect platforms in Integrations → Social promotion. Activate the Etsy listing before promoting so the funnel link works for buyers.

◆ What buyers receive

⚙ Troubleshooting

Etsy: "The requested redirect URL is not permitted"

The callback URL isn't saved in the app's Callback URL(s) field, or differs by a character (https vs http, trailing slash, missing port). Fix, save, wait 2–3 minutes, retry.

Etsy: "The application … is not recognized"

The keystring belongs to a different app than the one you edited, or the app is still pending review. Use one app for everything and check its status.

Etsy: "Shared secret is required in x-api-key header"

Save both the keystring and the shared secret in Integrations — Etsy requires the pair for API calls.

Publish button missing

It appears under "Generate Full Package" only when your Etsy shop is connected and you have completed packages from the last 24 hours.

"None of the selected mockups fit aspect ratio …"

That artwork's shape doesn't match any selected scene's frame (15% tolerance). Select scenes with matching frames or crop the art.

Printful: "This API endpoint applies only to … Manual Order / API platform"

Your connected Printful store is marketplace-connected (Etsy, Shopify…). Create an API store (Dashboard → Stores → Add store → "API") and reconnect Printful in Integrations — the API store is selected automatically.

Files skipped when publishing

Etsy's limits: 5 digital files, 20MB each. Connect Dropbox or Google Drive (recommended) or generate at 150 DPI so more files fit directly.

Printify: "shop … is not connected to sales channel" (code 8254)

Publishing needs the Printify store linked to Etsy — and the API token must come from the same Printify account that owns that store. See the Printify section's setup steps.

Still stuck? The server log (terminal running the app) and etsy_oauth.log usually name the exact problem.