> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Product Media

This API endpoint allows a merchant to manage product media such as images.

## Methods

* [product\_media.list](#product-media-list)
* [product\_media.types](#product-media-types)
* [product\_media.create](#product-media-create)
* [product\_media.update](#product-media-update)
* [product\_media.remove](#product-media-remove)

***

## Entity Properties

* [Image Type](#image-type-properties)
* [Image Mime Type](#image-mime-type)
* [Image Data](#image-data)

***

## `product_media.list`

`product_media.list (string $sku)`

Retrieve list of product images

### Parameters

**sku** `string`

Product SKU.

### Return Value

An array of objects. Each object will contain [Image Data](#image-data).

### Example Request

Get product images by product SKU:

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "product_media.list",
        [
            "product2"
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : [
        {
            "file" : "/b/l/blackberry8100_2.jpg",
            "position" : 1,
            "exclude" : 0,
            "url" : "http://magentohost/media/catalog/product/b/l/blackberry8100_2.jpg",
            "types" : [
                "image", 
                "thumbnail"
            ]
        }
    ]
}
```

### Error Codes

| code | message |
| - | - |
| 100 | Requested store view not found. |
| 101 | Product not exists. |

***

## `product_media.types`

`product_media.types (number $setId)`

Retrieve product image types

### Parameters

**setId** `integer`

Attribute set id.

### Return Value

An array of objects. Each object will contain [Image Type Properties](#image-type-properties).

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "product_media.types",
        [
            4        
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : [
        {
            "code" : "image",
            "scope" : "store"
        },
        {
            "code" : "thumbnail",
            "scope" : "store"
        }
    ]
}
```

***

## `product_media.create`

`product_media.create (string $sku, object $data)`

Upload new product image

### Parameters

**sku** `string`

Product SKU.

**data** `object`

Image data.

### Return Value

Image file name (e.g., "/i/m/image.png")

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "product_media.create",
        [
            "product2",
            {
                "file" : {
                    "content" : "base64 encoded content",
                    "mime": "image/jpeg"
                },
                "position" : 100,
                "types" : [
                    "thumbnail"
                ],
                "exclude" : 0
            }
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : [
        "/i/m/image.png"
    ]
}
```

### Error Codes

| code | message |
| - | - |
| 100 | Requested store view not found. |
| 101 | Product not exists. |
| 102 | Invalid data given. Details in error message. |
| 104 | Image creation failed. Details in error message. |
| 107 | Requested product doesn't support images |

***

## `product_media.update`

`product_media.update (string $sku, string $file, object $data)`

Update product image

### Parameters

**sku** `string`

Product SKU.

**file** `string`

Image file name.

**data** `object`

Image data.

### Return Value

`true`, if the image has been uploaded

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "product_media.update",
        [
            "product2",
            "/i/m/image.png",
            {
                "file" : {
                    "content" : "base64 encoded content",
                    "mime": "image/jpeg"
                },
                "position" : 100,
                "types" : [
                    "thumbnail"
                ],
                "exclude" : 1
            }
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : 1
}
```

### Error Codes

| code | message |
| - | - |
| 100 | Requested store view not found. |
| 101 | Product not exists. |
| 102 | Invalid data given. Details in error message. |
| 103 | Requested image not exists in product images' gallery. |
| 104 | Image creation failed. Details in error message. |
| 107 | Requested product doesn't support images |

***

## `product_media.remove`

`product_media.remove (string $sku, string $file)`

Remove product image

### Parameters

**sku** `string`

Product SKU.

**file** `string`

Image file.

### Return Value

`true`, if the image has been removed

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "product_media.remove",
        [
            "product2",
            "/b/l/blackberry8100_2.jpg"
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : 1
}
```

### Error Codes

| code | message |
| - | - |
| 100 | Requested store view not found. |
| 101 | Product not exists. |
| 106 | Image not removed. Details in error message. |
| 107 | Requested product doesn't support images |

## Entity Properties

### Image Type Properties

**Image Type Properties**

**code** `string`

A unique identifier for an image type. Allowed: "image", "thumbnail".

**scope** `string`

The "Scope" property. Allowed: "global", "website", "store".

### Image Mime Type

**Image Mime Type**

**image/jpeg** `string`

```json theme={null}
{ "mime" : "image/jpeg" }
```

JPEG

**image/gif** `string`

```json theme={null}
{ "mime" : "image/gif" }
```

GIF

**image/png** `string`

```json theme={null}
{ "mime" : "image/png" }
```

PNG

### Image Data

**Image Data**

**file** `object | string`

Creating a new file:

```json theme={null}
{ "file" : { "content" : "base64 encoded content", "mime" : "image/jpeg" }}
```

Retriving existing file:

```json theme={null}
{ "file" : "/b/l/blackberry8100_2.jpg" }
```

**position** `integer`

```json theme={null}
{ "position" : 3 }
```

**exclude** `integer`

```json theme={null}
{ "exclude" : 1 }
```

Allowed: "0" or "1".

**url** `string`

```json theme={null}
{ "url" : "https://shipstream.io/media/catalog/product/b/l/blackberry8100_2.jpg" }
```

**types** `array`

```json theme={null}
{ "types" : ["image", "thumbnail"] }
```

Allowed: "image", "thumbnail".


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.