n8n-nodes-sudomock

n8n community node for the SudoMock API. Integrate mockup rendering into your n8n workflows for Print-on-Demand automation.

SudoMock | Documentation | API Reference

Features

Account Operations

• Get Account Info: Retrieve account details, subscription plan, and usage statistics

PSD Mockups

• PSD Mockup: Upload: Upload PSD templates from a URL
• PSD Mockup: List: List all your uploaded PSD mockup templates with filtering and pagination
• PSD Mockup: Get: Get detailed information about a specific PSD mockup template
• PSD Mockup: Get Layers: List every layer of a PSD mockup, including the layers inside its smart objects, with the UUIDs Hidden Layers takes
• PSD Mockup: Update: Update the name of a PSD mockup template
• PSD Mockup: Delete: Delete a specific PSD mockup template

Photo Mockups

• Photo Mockup: Create: Create a reusable mockup from a product photo
• Photo Mockup: Get: Check preparation status and get the ready surfaces and print areas
• Photo Mockup: List: List your photo mockups
• Photo Mockup: Set Print Areas: Define print areas with four-point quads
• Photo Mockup: Render: Render artwork onto a ready surface or print area for 5 credits
• Photo Mockup: Delete: Delete a photo mockup

Rendering

• PSD Mockup: Render: Generate mockups with artwork, personalized text, or both. Text overrides support styled segments, fonts, size, color, stroke color, and overflow, shrink, or clip fitting. Optionally run asynchronously with the Run Asynchronously toggle, which returns a job_id to track with Get Job.
• Render Video: Turn a mockup (or an existing image URL) into a short product video (always asynchronous). Choose a supported duration, optional audio/motion, an optional one-off webhook, and optionally Wait for Completion to return the finished clip.
• Remove Background: Isolate the subject of an image onto a transparent background. The returned PNG URL is public and stays available for 7 days. Costs 25 credits, refunded automatically if processing fails. The same cleanup is available inline on both render operations with the per-artwork Remove Background toggle.

Fonts and Order Artwork

• Fonts: List available fonts, fetch one by UUID, upload a custom TTF or OTF from a public URL, and delete your custom fonts
• Artwork: Delete Stored Files: Delete stored order artwork by URL or mockup UUID

Async Jobs

• Get Job: Get the status and result of an async render, upload, video, or photo mockup job by its job_id. Terminal statuses are succeeded, failed, and cancelled (pending jobs report queued). On success it surfaces result_url (render/video) or mockup_uuid (upload and photo mockup creation). Optionally Wait for Completion to poll until the job finishes.
• List Jobs: List your async render, upload, video, and Photo Mockups jobs (keyset paginated, with optional kind and Mockup UUID filters).

Webhooks

• SudoMock Trigger: Start a workflow from selected SudoMock events with automatic signature verification. The endpoint it registers is pinned to the Photo Mockups event names (event_naming: current).
• Manage webhook endpoints that receive a signed HTTPS request the moment a job finishes:
• Webhook: List Endpoints
• Webhook: Get Endpoint
• Webhook: Create Endpoint (set an optional description, choose any event or leave empty for all, and pick the Event Naming the endpoint receives: current by default, or legacy)
• Webhook: Update Endpoint (change URL, description, enabled state, events, or re-pin Event Naming)
• Webhook: Delete Endpoint
• Webhook: Rotate Secret
• Webhook: Send Test
• Webhook: List Deliveries
• Webhook: Replay Delivery
• Webhook: Replay Failed Deliveries
• Webhook: Events Feed (recent deliveries across all of your endpoints)

Canonical events: render.succeeded, render.failed, upload.succeeded, video.succeeded, video.failed, photo_mockup.ready, photo_mockup.rejected, photo_mockup.failed, photo_mockup_render.succeeded, photo_mockup_render.failed, webhook.test. Endpoints created by earlier versions of this package are pinned to the legacy spelling of the five Photo Mockups events (2d_mockup.ready, 2d_mockup.rejected, 2d_mockup.failed, 2d_render.succeeded, 2d_render.failed) and keep receiving those names; both spellings can be selected when subscribing, the endpoint's Event Naming pin decides what is delivered, and Webhook: Update Endpoint can re-pin it. Deliveries are signed; see https://sudomock.com/docs/webhooks/overview for verification details.

Installation

Via n8n UI

In n8n, go to Settings → Community Nodes → Install and enter:

n8n-nodes-sudomock

Manual Installation

cd ~/.n8n/nodes
npm install n8n-nodes-sudomock

Restart n8n after installation.

Setup

1. Get Your API Key

1. Sign up at SudoMock
2. Go to Dashboard → API Keys
3. Create a new API key (starts with sm_)

2. Add Credentials in n8n

1. Create a new SudoMock node
2. Click on Credentials → Create New
3. Enter your SudoMock API Key
4. Save and test the connection

Operations

New SudoMock nodes first ask for a Resource, then show the operations for
that resource: Account, Artwork, Font, Image, Job, Photo Mockup, PSD Mockup,
Video, or Webhook. The default is PSD Mockup → PSD Mockup: Render.

Workflows saved with node version 1 keep their original Operation selector and
all existing settings when the package is updated. No workflow migration is
required. To use the grouped selector, add a new SudoMock node and select the
matching resource and operation. Do not change typeVersion in an existing
workflow JSON without also configuring its resource.

Get Account Info

Retrieve your account information, subscription details, and credit usage.

Output:

• Account: UUID, email, name, created date
• Subscription: Plan name, status, billing period
• Usage: Credits used/remaining, billing dates
• API Key: Name, creation date, last used, total requests

Example Output:

{
  "success": true,
  "data": {
    "account": {
      "uuid": "user-123",
      "email": "user@example.com",
      "name": "John Doe"
    },
    "subscription": {
      "plan": "pro-25k",
      "tier": "pro",
      "status": "active"
    },
    "usage": {
      "credits_used_this_month": 6250,
      "credits_limit": 25000,
      "credits_remaining": 18750,
      "prepaid_balance": 0,
      "prepaid_balance_currency": "USD"
    }
  }
}

An account is funded either by a subscription allowance or by a prepaid balance,
and the two are independent. The three credits_* fields describe the allowance
only. An account paying as it goes has no allowance, so it reports all three as 0
while holding a positive prepaid_balance and being perfectly able to pay:

"usage": {
  "credits_used_this_month": 0,
  "credits_limit": 0,
  "credits_remaining": 0,
  "prepaid_balance": 12.5,
  "prepaid_balance_currency": "USD"
}

PSD Mockup: Upload

Upload a PSD template from a public URL.

Parameters:

• PSD File URL (required): Public URL to your PSD file (up to Adobe's official PSD file size limit)
• Template Name (optional): Custom name for the template (auto-generated if not provided)

Example:

PSD URL: https://storage.example.com/mockup.psd
Name: T-Shirt Mockup Front

Output:

• Mockup UUID (use for rendering)
• Smart object UUIDs and details
• Thumbnail URLs

PSD Mockup: List

List all your uploaded mockup templates with optional filtering and pagination.

Parameters:

• Return All: Fetch all mockups or limit results
• Limit: Number of results (1-100, default: 20)
• Additional Options:
  • Filter by Name: Exact name match
  • Created After: Date filter
  • Created Before: Date filter
  • Sort By: created_at, updated_at, name
  • Sort Order: asc or desc

Example:

Limit: 20
Sort By: Created At
Sort Order: Descending

Output:
Each mockup as a separate item with full details (UUID, name, smart objects, thumbnails, etc.)

PSD Mockup: Get

Retrieve detailed information about a specific mockup template.

Parameters:

• Mockup UUID (required): UUID of the mockup to retrieve

Example:

Mockup UUID: c315f78f-d2c7-4541-b240-a9372842de94

Output:
Complete mockup details including all smart objects, thumbnails, and metadata.

PSD Mockup: Get Layers

List every layer of a mockup template, nested the way Photoshop's Layers panel shows them and front-most first. A smart object whose contents hold layers you can fill lists those layers as its children. An artboard has kind artboard, and its own layers are listed right before it at the top level rather than as its children. Costs no credits.

Parameters:

• Mockup UUID (required): UUID of the mockup

Output:
data.layers, where each layer has uuid, name, kind, visible and children. Put a layer's uuid in Hidden Layers on PSD Mockup: Render to leave it out of one render.

PSD Mockup: Update

Update the name of a mockup template.

Parameters:

• Mockup UUID (required): UUID of the mockup to update
• New Name (required): New name for the template

Example:

Mockup UUID: c315f78f-d2c7-4541-b240-a9372842de94
New Name: Updated T-Shirt Mockup

Output:
Updated mockup details with the new name.

PSD Mockup: Render

Generate a mockup by filling smart objects with your designs.

Parameters:

• Mockup UUID (required): UUID from the PSD Mockup: Upload response

• Smart Objects: One or more smart objects to fill. Optional when Text Layers or Hidden Layers is set.

  • Smart Object UUID
  • Design URL (PNG, JPG, WebP)
  • Fit Mode: fill, contain, or cover (recommended)
  • Additional Options (optional):
    • Rotation: -360 to 360 degrees
    • Remove Background: clean the artwork before placing it (adds 25 credits per artwork)
    • Color Overlay: Hex color code
    • Color Blend Mode: Various blend modes
    • Brightness: -150 to 150
    • Contrast: -100 to 100
    • Opacity: 0-100

• Hidden Layers (optional): JSON array of up to 50 layer UUIDs from PSD Mockup: Get Layers to leave out of this render, including layers inside a smart object. Hiding a group hides every layer inside it. Works on its own.

• Export Options (optional):

  • Image Format: WebP (recommended), PNG, or JPEG
  • Image Size: Width in pixels (100-10000, default 2048)
  • PSD's Own Size and Resolution: render at the template's own width, with the resolution the PSD was saved with unless DPI is set
  • Quality: 1-100 for JPG/WebP
  • Export Label: Custom label for file naming

Example:

Mockup UUID: abc123-def456
Smart Object 1:
  - UUID: so-uuid-001
  - Design URL: https://cdn.example.com/design.png
  - Fit Mode: Cover
  - Brightness: 10
  - Contrast: 5

Export Options:
  - Format: WebP
  - Size: 1920
  - Quality: 95

Output:

{
  "success": true,
  "renderedImageUrl": "https://cdn.sudomock.com/renders/abc123.webp",
  "allRenderedUrls": [
    "https://cdn.sudomock.com/renders/abc123.webp"
  ],
  "data": {
    "print_files": [...]
  }
}

Remove Background

Isolate the subject of an image onto a transparent background. The returned PNG URL is public and stays available for 7 days.

Parameters:

• Image URL (required): public URL of the image to process

Example:

Image URL: https://cdn.example.com/product-photo.jpg

Output:

{
  "success": true,
  "data": {
    "url": "https://cdn.sudomock.com/bg-cutouts/abc123.png",
    "width": 2000,
    "height": 2000,
    "credits_charged": 25
  }
}

The returned URL is public, stays available for 7 days and can be fed straight into PSD Mockup: Render or Photo Mockup: Render as artwork during that window. Processing costs 25 credits per image and is refunded automatically if it fails. To clean artwork as part of a render instead, use the per-artwork Remove Background toggle on either render operation.

PSD Mockup: Delete

Delete a specific mockup template.

Parameters:

• Mockup UUID (required): UUID of the mockup to delete

Example:

Mockup UUID: c315f78f-d2c7-4541-b240-a9372842de94

Output:
Deletion confirmation

Photo Mockup Operations

Create, prepare, render, and manage reusable mockups from product images without a PSD.

1. Photo Mockup: Create accepts a public source_url or source_base64, plus an optional name. By default it waits and returns the ready mockup detail unchanged. Enable Run Asynchronously to receive a 202 job with job_id and status_url, then use Get Job when needed.
2. Photo Mockup: Get returns draft, ready, or failed status. Poll this operation until the mockup is ready. The ready response lists every printable product in data.surfaces (addressed by surface_uuid), and every print area someone has drawn in data.quads (addressed by print_area_id).
3. Photo Mockup: List returns your photo mockups with limit, offset, and shopper-customizable filtering.
4. Photo Mockup: Set Print Areas replaces saved areas with quads made from four [x, y] coordinate pairs. It can also send an empty list; the API remains authoritative and accepts that only when the mockup can remain renderable without saved areas.
5. Photo Mockup: Render accepts the mockup UUID and one or more ready render targets. Each target names exactly one address: uuid for a saved print area, or surface_uuid for a surface. Each target also includes either an artwork URL or Base64 artwork, with optional background removal (adds 25 credits per artwork), color, public adjustments, and placement. Export options support PNG, JPG, or WebP from 100 to 10000 pixels, plus quality and optional DPI. Each render costs 5 credits and returns print_files, where print_files[0] is the CDN URL.
6. Photo Mockup: Delete deletes the selected photo mockup.

A surface and a print area are separate render targets. Saving a print area on a
product does not close off the surface under it, so an all-over print and a chest
logo can both be addressed on the same product, in the same call, as two targets.

Placement is where the two kinds differ:

• A surface target takes Coverage, a percentage from 10 to 100. Leave it out
  and the artwork covers the whole surface.
• A print area target takes either Fit (contain, fill, or cover), which
  always sizes the artwork to the whole area, or an explicit Width and Height
  pair when you want to choose the box yourself. Send one or the other, never both,
  and send Width and Height together. Leaving Fit out is the same as contain.

Both kinds take position, offset, and rotation. Anything you do not set is not sent,
so the API decides it.

Create must reach ready through Photo Mockup: Get before Photo Mockup: Render.

Render Video

Turn a mockup (or an existing image URL) into a short product video. Always asynchronous: returns a job_id you can track with Get Job.

Parameters:

• Input Mode: Render Mockup (render a mockup with your designs first) or Animate Image URL (animate a public image directly)
• Mockup UUID (required in Render Mockup mode): UUID of the mockup to animate
• Smart Objects (required in Render Mockup mode): one or more smart objects with a Design URL and Fit Mode
• Image URL (required in Animate Image URL mode): public HTTPS image (.png, .jpg, .jpeg, .webp, .gif, .avif)
• Webhook URL (optional): one-off HTTPS URL notified when this job finishes
• Video Options:
  • Duration (Seconds): clip length (default 4; must be an allowed duration for the chosen model — the default model veo-3.1-fast allows 4 or 6; max 15)
  • Audio: include a generated audio track (default false; may cost extra credits depending on model)
  • Motion: ambient (default) or showcase
  • Advanced Model: optional override pinning a roster model (veo-3.1-fast, kling-v3-pro, kling-2.6-pro, seedance-2.0, wan-2.5); leave empty to auto-pick by plan tier
• Wait for Completion: poll the job and return the finished clip instead of the queued job
• Poll Timeout (Seconds): max wait when Wait for Completion is on

Output:
The 202 acknowledgement (job_id, kind, status, status_url, estimated_credits, ...), or the finished job (with result_url / resultUrl) when Wait for Completion is on.

Get Job

Track an asynchronous render, upload, video, or photo mockup job by its job_id.

Parameters:

• Job ID (required): the job_id from an async render, upload, video, or photo mockup request
• Wait for Completion: poll until a terminal status (succeeded, failed, cancelled)
• Poll Timeout (Seconds): max wait when Wait for Completion is on

Output:
The job object. On success it surfaces result_url / resultUrl (render/video) or mockup_uuid / resultMockupUuid (upload), plus credits_charged and payg when applicable.

List Jobs

List your async render, upload, video, and Photo Mockups jobs (newest first, keyset paginated).

Parameters (all optional, under Filters):

• Kind: render, upload, video, photo_mockup_create, or photo_mockup_render (the older 2d_create / 2d_render spellings name the same jobs; filtering by either returns both)
• Mockup UUID: only jobs derived from this source mockup
• Limit: 1-50 (default 20)
• Cursor: opaque next_cursor from a previous response for pagination

Output:
{ jobs: [...], next_cursor }.

Note: Bulk "delete all mockups" is intentionally not exposed: the API accepts DELETE /psd-mockups/all only from a dashboard sign-in, so it is not callable with an API key. Delete mockups individually with PSD Mockup: Delete, or use the SudoMock dashboard.

Webhook Operations

Manage webhook endpoints and their deliveries. See the Webhooks feature list above for the full operation set and the canonical event types.

Common parameters:

• Webhook Endpoint ID (required for get/update/delete/rotate/test/deliveries/replay/replay-failed)
• Endpoint URL + Description (create) and Events (create/update): leave Events empty to subscribe to all
• Event Naming (create, default current; update under Update Fields): which spelling of the Photo Mockups events the endpoint receives, current (photo_mockup.*, kind photo_mockup_*) or legacy (2d_mockup.*, kind 2d_*)
• Delivery ID (replay)
• Webhook: Events Feed takes no parameters (returns recent deliveries across all your endpoints)

Example Workflows

Ready-to-use n8n workflows are available in the examples/ folder:

1. Complete API Test Workflow

File: examples/complete-test-workflow.json

Tests the core mockup operations in sequence:

• Get Account Info → Upload PSD → Get Mockup → List Mockups
• Render Mockup → Update Name → Verify Update → Delete Mockup

Perfect for verifying your setup and understanding the complete workflow.

View Details →

2. Rate Limit Handling Workflow

File: examples/rate-limit-test-workflow.json

Demonstrates proper rate limit error handling with automatic retry logic:

• Detects 429 errors
• Extracts retry-after value
• Waits and automatically retries
• Shows detailed error information

View Details →

3. Sequential Batch Render Workflow

File: examples/batch-render-workflow.json

Demonstrates the power of n8n workflows with sequential batch processing:

• Renders 10 mockups one after another
• Uses different designs for each render
• 2-second delay between renders to avoid rate limits
• Progress tracking and final summary with all rendered URLs

Perfect for understanding batch processing and workflow automation.

View Details →

Quick Start with Examples

1. Import a workflow:

   n8n UI → Workflows → Import from File → Select workflow JSON
   

2. Configure credentials:

   Click any SudoMock node → Credentials → Select your API key
   

3. Execute:

   Click "Execute Workflow" button
   

See examples/README.md for detailed instructions, customization options, and troubleshooting.

Usage Examples

Example 1: Complete Mockup Workflow

1. [HTTP Request]
   → Download PSD from URL

2. [SudoMock: Upload PSD]
   → Upload template
   → Extract: mockupUuid, smartObjectUuid

3. [SudoMock: Render Mockup]
   → Use extracted UUIDs
   → Add design URL
   → Get: renderedImageUrl

4. [Etsy/Shopify Node]
   → Create product listing
   → Use rendered mockup image

Example 2: Batch Process Designs

1. [Airtable Trigger]
   → Get list of designs to process

2. [SudoMock: List Mockups]
   → Get available templates

3. [Loop Over Designs]
   → [SudoMock: Render Mockup]
   → Generate mockup for each design

4. [Store Results]
   → Save rendered URLs to database

Example 3: Account Monitoring

1. [Schedule Trigger]
   → Run daily at 9 AM

2. [SudoMock: Get Account Info]
   → Check credit usage

3. [IF Node]
   → If credits_limit > 0
       AND credits_remaining < 5% of credits_limit
     OR credits_limit == 0
       AND prepaid_balance < 5

4. [Send Email/Slack]
   → Alert about low funds

Alert on whichever way the account is actually funded, because the two branches
measure different things and neither one alone is correct.

An account with a subscription has an allowance, so watch credits_remaining
against credits_limit. Use a percentage rather than a fixed number: the
allowance ranges from 5,000 to 100,000 depending on the plan, so a threshold
tuned for one plan is noise on another.

An account paying as it goes has no allowance at all. It reports
credits_limit: 0 and credits_remaining: 0 permanently, and those numbers
never reset, so a bare credits_remaining < 100 fires forever on an account
that is fully funded. Watch prepaid_balance for that account instead.

Do not build a percentage or a progress bar out of prepaid_balance. It is an
amount, not a fraction, and it has no denominator to be a percentage of. For the
same reason, never report the pair as 0 / 0: that reads as an empty account
when it means the allowance is simply not the thing paying.

Rate Limits

Request Rate Limits

All authenticated users have a base rate limit of 1000 requests per minute with burst capacity of 1500 requests.

Unauthenticated requests (IP-based): 30 requests per minute

Concurrent Request Limits (Plan-Based)

Rate Limit Error Handling

The node automatically detects and handles two types of rate limit errors:

1. Request Rate Limit Exceeded (1000 RPM)

Error Output:

{
  "error": "Rate limit exceeded (1000 requests/minute). Please retry after 42 seconds.",
  "operation": "render",
  "statusCode": 429,
  "retryAfter": 42,
  "errorType": "rate_limit_exceeded",
  "errorDetails": {
    "type": "rate_limit_exceeded",
    "limit": 1000,
    "remaining": 0
  }
}

2. Concurrent Limit Exceeded (Plan-Based)

Error Output:

{
  "error": "Concurrent render limit reached (11/10). Please wait 5 seconds and try again.",
  "operation": "render",
  "statusCode": 429,
  "retryAfter": 5,
  "errorType": "concurrent_limit_exceeded",
  "errorDetails": {
    "type": "concurrent_limit_exceeded",
    "resource": "concurrent-render",
    "limit": 10,
    "current": 11
  }
}

Best Practices

1. Enable "Continue On Fail" in n8n node settings to capture rate limit errors without stopping the workflow
2. Implement retry logic using the retryAfter value from error output
3. Monitor errorType to distinguish between request rate limits and concurrent limits
4. Use n8n's "Wait" node with {{$json.retryAfter}} seconds before retrying

Example: Retry Logic Workflow

[SudoMock Render] (Continue On Fail: ON)
    → [IF: Check statusCode]
        → If 429: [Wait: {{$json.retryAfter}} seconds]
            → [SudoMock Render Again]
        → Else: Continue

Error Handling

All operations support the Continue On Fail option in n8n. When enabled:

• Errors are captured as output items
• Workflow continues to next item
• Error details included in output

Example Error Output:

{
  "error": "Rate limit exceeded. Retry after 42 seconds.",
  "operation": "render"
}

Development

Setup

# Clone repository
git clone https://github.com/sudomock/n8n-nodes-sudomock.git
cd n8n-nodes-sudomock

# Install dependencies
pnpm install

# Build
pnpm build

# Development (watch mode)
pnpm dev

Testing Locally

# Link package globally
npm link

# Link in n8n's custom nodes
cd ~/.n8n/custom
npm link n8n-nodes-sudomock

# Start n8n
n8n start

Access n8n at http://localhost:5678 and search for "SudoMock" in the nodes panel.

Build Commands

# Build TypeScript and icons
pnpm build

# Format code
pnpm format

# Lint code
pnpm lint

# Fix linting issues
pnpm lintfix

Resources

• SudoMock Website
• API Documentation
• n8n Documentation
• Report Issues

License

MIT

Support

• Email: hello@sudomock.com
• Documentation: https://sudomock.com/docs
• Community: https://community.n8n.io

Made with ❤️ for the n8n community