Working with Images

Supported Sizes

The following image sizes are officially supported by Etsy:

The 570xN and fullxfull image sizes have variable dimensions depending on the original artwork uploaded by the seller:

• For the 570xN size, the horizontal dimension will be the original artwork's horizontal size, or 570 pixels, whichever is smaller.
• For the fullxfull size, the horizontal dimension will be the original artwork's horizontal size, or 3000 pixels, whichever is smaller.
• Both sizes will have a variable vertical dimension, dependent on the original artwork's aspect ratio.

Resizing, Cropping and Caching Images

If the provided sizes don't suit your application, you are free to download the larger image sizes, resize and cache them for your own use, as long as you adhere to our API Terms of Use.

Uploading Images

Image uploads can be performed using a POST request with the Content-Type: multipart/form-dataheader, following RFC1867. This is identical to using curl -F, except that that request needs to be signed using OAuth.

Your OAuth toolkit must support multipart form uploads as described above. Here is example code for PHP using the PECL OAuth 1.1 extension (PECL OAuth 1.0 will not work):

// You must define the constants OAUTH_CONSUMER_KEY and OAUTH_CONSUMER_SECRET
// You must also assign values to the variables $access_token, $access_token_secret,
// $listing_id and $filename, and $mimetype.
// Your image file is assumed to be in the same directory as this code.

$oauth = new OAuth(OAUTH_CONSUMER_KEY, OAUTH_CONSUMER_SECRET);

$oauth->enableDebug();
$oauth->setToken($access_token, $access_token_secret);

try {
    $source_file = dirname(realpath(__FILE__)) ."/$filename";

    $url = "https://openapi.etsy.com/v2/listings/".$listing_id."/images";
    $params = array('@image' => '@'.$source_file.';type='.$mimetype);

    $oauth->fetch($url, $params, OAUTH_HTTP_METHOD_POST);

    $json = $oauth->getLastResponse();
    print_r(json_decode($json, true));

} catch (OAuthException $e) {
    // You may want to recover gracefully here...
    print $oauth->getLastResponse()."\n";
    print_r($oauth->debugInfo);
    die($e->getMessage());
}

Watermarked Images

If your app adds a visual watermark to existing listing images, you must set is_watermarked=true when using the uploadListingImage method.