Skip to main content

Uploading Media

Upload images and media files to Trustana using a secure 2-step process. This guide covers the complete workflow from file preparation to automatic association with products and variants.

Integration Pre-requisites

Before uploading media, ensure you understand:

Upload Process:

  • Media upload is a 2-step process: prepare → upload to S3
  • Files are uploaded individually (no batch uploads)
  • Automatic association with SKUs and media galleries after upload completion

File Requirements:

  • Supported formats: jpg, jpeg, png, gif, webp, bmp, tiff
  • fileName must include an image extension
  • Up to 100 unique SKU IDs per upload

See Getting Started for API authentication and Creating Products for product integration workflows.

Upload Workflow​

2-Step Upload Process​

The media upload follows a secure 2-step process that integrates seamlessly with Trustana's product management:

Step 1: Prepare the Upload​

This is what the sample JSON was for. It's not the binary; it's the prepare request.

Request​

curl -X POST https://api.trustana.com/v1/upload/prepare \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "product-image3.jpg",
    "skuIds": ["SKU123", "SKU456"],
    "addToMediaGallery": true
  }'

Request Parameters​

  • fileName: Must include an image extension (jpg, jpeg, png, gif, webp, bmp, tiff)
  • skuIds: Array of up to 100 unique SKU IDs
  • addToMediaGallery: Boolean to add image to media gallery

Response Example​

{
  "errorCode": 0,
  "data": {
    "uploadUrl": "https://s3.amazonaws.com/...",
    "expiresIn": 900,
    "fileName": "image-123-1700000000000.jpg",
    "finalUrl": "https://cdn.trustana.com/.../image-123-1700000000000.jpg",
    "uploadId": "upl_01hxyz..."
  }
}

Response Fields:

  • uploadUrl: Pre-signed S3 URL for file upload
  • expiresIn: URL expiration time in seconds (900 = 15 minutes)
  • fileName: Unique name we track (generated from your fileName)
  • finalUrl: CDN URL where the image will be available after processing
  • uploadId: Per-file tracking ID for status polling

Step 2: Upload the Actual File (to S3)​

Use the uploadUrl from step 1. There's no Trustana endpoint to send the binary—S3 accepts it directly.

Binary Upload to S3​

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --upload-file ./product-image3.jpg

Important Notes:

  • Use the correct Content-Type for your image format
  • Upload the raw file bytes directly to S3
  • No Trustana authentication needed for S3 upload
  • The uploadUrl expires in 15 minutes

Processing is asynchronous; poll until you get a fileId.

Check Status by uploadId​

curl -X GET "https://api.trustana.com/v1/upload/status?uploadId=upl_01hxyz..." \
  -H "X-API-Key: YOUR_API_KEY"

Check Status by fileName​

curl -X GET "https://api.trustana.com/v1/upload/status?fileName=image-123-1700000000000.jpg" \
  -H "X-API-Key: YOUR_API_KEY"
Processing Time

If you call immediately after S3 upload, you might get 404 while the file is still being processed—just retry after a short delay (2-5 seconds).

Response When Processing Complete​

{
  "errorCode": 0,
  "data": {
    "fileId": "IM16127893",
    "key": "424/PRODUCT_IMAGE/.../image-123.jpg",
    "originalName": "product-image3.jpg",
    "size": 208049,
    "format": "image/png",
    "createdAt": 1759261154858
  }
}

SKU Association & Media Gallery​

Automatic Processing​

The associations you sent in prepare (skuIds, addToMediaGallery) are applied automatically once the file finishes processing.

Key Points:

  • uploadId is per file (not a "bucket"). It's only for tracking during upload
  • The durable identifier you'll use elsewhere is fileId (e.g., IM16127893)
  • SKU associations and media gallery updates happen automatically
  • No additional API calls needed after getting the fileId

Timeline​

  • S3 Upload: Immediate (seconds)
  • Processing: 30 seconds - 2 minutes
  • SKU Association: Automatic after processing
  • CDN Availability: 2-5 minutes

Best Practices​

Performance Optimization​

  • Validate files locally before calling /upload/prepare
  • Use appropriate timeouts for S3 uploads (30-60 seconds)
  • Implement retry logic for status polling
  • Upload files in parallel when possible (respect rate limits)

Error Recovery​

  • Check file format before starting upload process
  • Handle expired URLs by calling prepare again
  • Implement exponential backoff for status polling
  • Log uploadId and fileName for debugging

Integration Strategies​

  • Pre-upload workflow: Upload all media first, then create products
  • Real-time workflow: Upload media with specific SKU associations during updates
  • Batch processing: Upload multiple files sequentially with proper error handling

Next Steps​

After mastering media upload, explore related workflows:

Product Integration​