Configure Image Domains

Image domains control which external domains can serve images in your Stash Pay shop. When you add an image domain, Stash Pay validates that all external images come from allowed domains. Images from unauthorized domains are blocked.

Images from allowed domains are automatically optimized through Stash Pay's image proxy: resized, compressed, and converted to modern formats (AVIF/WebP) when supported by the browser.

Domain Patterns

Image domains support two pattern types:

Exact Domain: example.com

• Matches only example.com
• Does not match subdomains like cdn.example.com

Wildcard Domain: *.example.com

• Matches example.com and all subdomains
• Matches cdn.example.com, assets.cdn.example.com, etc.

Configure Image Domains

Domain Format Requirements

Valid examples:

• example.com
• *.example.com
• cdn.example.com
• *.stash.gg

Invalid examples:

• http://example.com (includes protocol)
• 192.168.1.1 (IP address)
• example (no TLD)

Using Images

Stash Pay uses Next.js <Image> component with a custom loader. Images are automatically optimized when loaded:

import Image from 'next/image';

<Image
  src="https://cdn.example.com/product-image.jpg"
  alt="Product image"
  width={500}
  height={300}
/>

Image Optimization

The image proxy automatically:

• Resizes images to requested dimensions
• Converts to AVIF (best) or WebP (good) when browser supports them, falls back to original format
• Compresses with quality settings (default: 75%)
• Caches optimized images for 4 hours in production

Supported Formats

• Input: JPEG, PNG, GIF, WebP, AVIF, SVG
• Output: AVIF (if browser supports), WebP (if browser supports), or original format

Best Practices

Use wildcards for CDN subdomains: If you use multiple CDN subdomains, use *.yourcdn.com to match all subdomains.

Be specific when possible: For security, prefer specific domains over wildcards when you only need one subdomain (e.g., cdn.example.com instead of *.example.com).

Add domains before going live: Add all required image domains during development/testing to avoid broken images in production.

Test after adding: Wait 10-15 minutes, then test loading an image from that domain and check the browser console for errors.

Troubleshooting

Images Not Loading

If images from an allowed domain are not loading:

1. Verify domain configuration: Check that the domain is added in Stash Studio → Project Settings → Image Domains and the pattern matches exactly (case-sensitive)
2. Wait for activation: New domains take 10-15 minutes to activate
3. Check image URL: Ensure the URL uses HTTPS and the hostname matches your configured domain pattern
4. Check browser console: Look for 403 errors (domain not allowed) or other network errors

Common Errors

"Image domain already exists": The domain is already configured. Check the Image Domains table in Stash Studio → Project Settings → Image Domains.

"Invalid domain name pattern":

• Remove http:// or https:// prefix
• Ensure the domain has a valid TLD (e.g., .com, .net)
• Don't use IP addresses
• Check for typos

Images loading slowly:

• First request may be slower as the proxy fetches and optimizes the image
• Subsequent requests are cached for 4 hours
• Very large source images take longer to process

Images not optimized:

• Check if your browser supports AVIF/WebP
• Clear browser cache to see newly optimized images
• Very small images may not benefit from optimization
• SVG files are passed through without conversion

API Reference

Add Image Domain

Endpoint: POST /studio/partner/{partner_id}/shop/{shop_id}/image-domains/add

{
  "domain_name_pattern": "example.com"
}

Response: 200 OK (empty body)

List Image Domains

Endpoint: GET /studio/partner/{partner_id}/shop/{shop_id}/image-domains/all

{
  "domain_name_patterns": [
    "example.com",
    "*.cdn.example.com"
  ]
}

Delete Image Domain

Endpoint: DELETE /studio/partner/{partner_id}/shop/{shop_id}/image-domains/{domain_name_pattern}/delete

Response: 200 OK (empty body)

Security and Limitations

Security:

• Only domains you explicitly allow can serve images
• External images must use HTTPS
• IP addresses are not allowed (must use domain names)
• Wildcard patterns (*.example.com) allow all subdomains—use carefully

Limitations:

• New domains take 10-15 minutes to become active
• Optimized images are cached for 4 hours
• Some exotic image formats may not be optimized
• Very large images may take longer to process