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.

Creating the Dropbox app — detailed walkthrough (one time, by the app operator)

  1. Open dropbox.com/developers/apps and log in with the Dropbox account you want to use.
  2. Click the blue Create app button (top right).
  3. Step "Choose an API": select Scoped access.
  4. Step "Choose the type of access": select App folder — uploads stay sandboxed inside Apps/<your app name>/ and the app can never touch the rest of your Dropbox.
  5. Name the app (e.g. MockupGenerator-Bundles). Names are unique across all of Dropbox — if it's taken, add a suffix.
  6. Tick the terms checkbox → Create app. You land on the app's console page.
  7. Open the Permissions tab. Tick exactly these two scopes:
    files.content.write (upload the bundle ZIPs)
    sharing.write (create the buyer download links)
    Then click Submit in the banner at the bottom — unticked or unsubmitted scopes are the #1 setup mistake.
    Do this before anyone clicks Connect: tokens issued earlier never gain new permissions. If you got the order wrong, Disconnect and Connect again in Integrations.
  8. Open the Settings tab → section "OAuth 2" → Redirect URIs: type http://localhost:8000/dropbox/callback and click Add. When you deploy, come back and also add https://yourdomain.com/dropbox/callback (production must be https — Dropbox only allows plain http for localhost). Multiple URIs can be registered at once.
  9. Still in Settings, copy the App key (not the secret) into the server's .env file as DROPBOX_APP_KEY=<key>, then restart the server.
  10. Verify: log into the app → Integrations → Connect Dropbox → Allow → ✓ page. The header button next to Settings turns blue "Dropbox ✓"; after your first publish it opens Apps/<app name>/Etsy Bundles/ with the uploaded ZIPs.

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.

Creating the Google app — detailed walkthrough (one time, by the app operator)

  1. Open console.cloud.google.com and log in with any Google account (it does not have to be the Drive account you'll connect later).
  2. In the top bar click "Select a project" → in the dialog click New Project → name it (e.g. MockupGenerator) → Create, then make sure it's the selected project in the top bar.
  3. Enable the Drive API — do not skip: click the ☰ navigation menu (three lines, top left) → APIs & Services → Library → search "Google Drive API" → open it → Enable.
    This step is easy to miss and fails silently: connecting still succeeds, but every upload is rejected with 403 accessNotConfigured and bundles never appear in Drive. If you skipped it, enable the API now — existing connections start working within a few minutes, no reconnect needed.
  4. Consent screen / create the app: ☰ navigation menu → APIs & Services → OAuth consent screen → Get started / Create app: app name + your support email → audience External → contact email → finish. No scopes need adding.
  5. Create the OAuth client: from the consent screen you're offered Create OAuth client (otherwise: ☰ → APIs & Services → Credentials → + Create credentials → OAuth client ID). Application type Web application → name it → under Authorized redirect URIs click Add URI and enter your app's callback, e.g.:
    https://5-161-185-121.sslip.io/gdrive/callback
    Add one entry per URL the app runs on (local dev, deployed server — multiple URIs are allowed). The path is always /gdrive/callback. → Create.
  6. Add test users: ☰ → APIs & Services → OAuth consent screen → Audience (or "Test users") → + Add users → enter the Gmail address of every account that will connect a Drive (your own at minimum). Skipping this is the #1 mistake — Google blocks everyone else with "access_denied" while the app is unverified.
  7. Copy the credentials: a dialog shows them right after client creation, or find them anytime under ☰ → APIs & Services → Credentials → click your client. Copy the Client ID (ends in .apps.googleusercontent.com) and the Client secret into the server's .env — exact format matters (UPPERCASE names, =, no spaces or colons):
    GOOGLE_CLIENT_ID=<client id>
    GOOGLE_CLIENT_SECRET=<client secret>
    then restart the server.
  8. Verify: log into the app → user menu → Integrations → Google Drive card → Connect Google Drive → pick your Google account → you'll see "Google hasn't verified this app" (normal while unverified) → Continue → Allow → ✓ page. The card now shows your account email.
Token lifetime while "Testing": Google expires app access after 7 days while the consent screen is in Testing status, so you'd reconnect weekly. Fix: OAuth consent screen → Publish app (status "In production"). Users then see a stronger unverified-app warning until Google verification, but connections stop expiring.

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.

📣 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.

Google Drive: "Not available (platform Google app missing)"

GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET aren't set in the server's .env — complete the Google Cloud walkthrough in the Google Drive section and restart the server. Being logged into Google in your browser is not a connection.

Google: "Error 403: access_denied" during Connect

The Google account you picked isn't on the app's Test users list (OAuth consent screen → Test users → Add) — or publish the consent screen to production.

Google: "redirect_uri_mismatch"

The exact URL the app runs on isn't registered: Google Cloud → Credentials → your OAuth client → Authorized redirect URIs must contain <your-app-url>/gdrive/callback character-for-character (scheme, host, no trailing slash).

Google Drive connected, but bundles never appear in Drive

Almost always 403 accessNotConfigured: the Google Drive API was never enabled on the Cloud project. Google Cloud console → your project → ☰ → APIs & Services → Library → "Google Drive API" → Enable (the 403 error message even contains a direct enable link with your project number). Wait 2–3 minutes; no reconnect needed. The server log shows "[Etsy] Google Drive upload failed" with the same reason.

Google Drive disconnects after ~7 days

The consent screen is still in "Testing" status — Google expires tokens weekly there. OAuth consent screen → Publish app.

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.