n8n + Ratio Ready: automate Etsy image processing

Node 1 — Trigger

Local File Trigger (or Webhook)

Add a Local File Trigger node. Set Watch to the folder where you drop design files. Set Events to added. Enable Read File Content so the binary data flows into the next node automatically.

If your files arrive via webhook (e.g. a Zapier trigger or a custom export script), use a Webhook node instead and set Response Mode to Immediately. You'll need to read the binary file separately via an Read Binary File node if the webhook only passes a URL.

Node 2 — Submit batch

HTTP Request → POST /v1/batch/wallart

Add an HTTP Request node.

The response will be 202 Accepted with a JSON body containing batchId. Add a Set node after this to extract {"{{ $json.batchId }}"} into a workflow variable you can reference in later nodes.

For clipart batches, change the URL to /v1/batch/clipart and the payload to {"{"}"printSize": 4096, "generatePreview": true{"}"}. Clipart accepts up to 50 files in the same images field — the same plural field name every /v1/batch/* endpoint uses.

Node 3 — Poll for completion

Wait → HTTP Request (GET /v1/batch/:id) → IF loop

Add a Wait node. Set Resume to After time interval, value 2 seconds. This is the polling interval — 2 seconds is a reasonable starting point for wall art (which takes 10–60 seconds depending on image size).

After the Wait node, add another HTTP Request node:

Add an IF node after the poll request. Set the condition: {"{{ $json.status }}"} equals completed. The false branch loops back to the Wait node. The true branch continues to the download node.

Node 4 — Download assets

HTTP Request → download ZIP or individual files

The GET /v1/batch/:id response includes a downloadUrl (the master ZIP) and per-file children[n].printUrl, previewUrl, and mockupUrls[]. These are presigned Cloudflare R2 URLs that expire after 24 hours.

For an Etsy workflow, you typically want the preview images (2048px listing-ready JPGs) and the print files (300 DPI master). Add an HTTP Request node for each file you need:

For the full ZIP, use the downloadUrl field instead. Use a Split In Batches node if you want to process each ratio file from a wall art batch separately.

Node 5 — Create Etsy draft

Etsy node (or HTTP Request to Etsy v3 API)

n8n has a built-in Etsy node. Use the Create Listing operation. Map the fields from the batch result:

After creating the listing (which returns a listing_id), upload the listing images via a separate HTTP Request to POST /v3/application/shops/:shop_id/listings/:listing_id/images — the built-in Etsy node does not handle image uploads directly. Pass the binary mockup image as image in a multipart form body (Etsy's own field name here is singular image).

For digital download listings, you also need to upload the print file as a listing file using Etsy's POST /v3/application/listings/:listing_id/files endpoint.

Don't poll faster than 2 seconds

The Ratio Ready API applies rate limits. Polling at sub-second intervals will get you rate-limited before the batch even has time to complete. A 2-second Wait interval is fine for interactive use; if you're running overnight batches, 5 seconds is more considerate to shared infrastructure.

Add error branches to every HTTP Request node

In n8n, enable Continue On Fail on your HTTP Request nodes and add an IF node that checks {"{{ $json.error }}"}. Route errors to a Send Email or Slack node so you know when something fails — a 402 (insufficient credits) or 401 (expired token) would otherwise silently stall your workflow.

For the polling loop specifically, add a counter in a Code node and break the loop after 60 attempts (2 minutes at 2s intervals) to avoid infinite loops on stuck batches.

Store the API key as an n8n credential, never inline

Go to n8n Settings → Credentials → Add Credential → HTTP Header Auth. Set Name to Authorization and Value to Bearer pk_your_key. Reference it in each HTTP Request node via Predefined Credential Type → Header Auth. This prevents the key from appearing in workflow JSON exports and keeps it out of logs.

Use Split In Batches for large design volumes

If you're processing many images at once (e.g. a folder of 20 new designs), don't submit them all as separate parallel HTTP Request calls simultaneously. Add a Split In Batches node before the submit step and set Batch Size to 3–5. This keeps your n8n instance responsive and avoids hitting the Ratio Ready processing queue limit. Each batch runs sequentially and the workflow handles them in order.

Wall art vs clipart: different field names

Wall art uses image (singular) in the form data. Clipart uses images (plural, accepts multiple files). Using the wrong field name silently sends no image and the API returns a validation error. If your POST keeps returning INVALID_INPUT, check the field name first.

Download URLs expire after 24 hours

The printUrl, previewUrl, mockupUrls, and downloadUrl values are presigned Cloudflare R2 URLs. They are only valid for 24 hours from batch completion. If your workflow involves manual review before uploading to Etsy, download the files to local storage or Google Drive immediately after the batch completes — don't rely on the R2 URLs still being valid the next day.