> ## 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

<ParamField path="sku" type="string">
  Product SKU.
</ParamField>

### 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

<ParamField path="setId" type="integer">
  Attribute set id.
</ParamField>

### 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

<ParamField path="sku" type="string">
  Product SKU.
</ParamField>

<ParamField path="data" type="object">
  Image data.
</ParamField>

### 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

<ParamField path="sku" type="string">
  Product SKU.
</ParamField>

<ParamField path="file" type="string">
  Image file name.
</ParamField>

<ParamField path="data" type="object">
  Image data.
</ParamField>

### 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

<ParamField path="sku" type="string">
  Product SKU.
</ParamField>

<ParamField path="file" type="string">
  Image file.
</ParamField>

### 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

<Expandable title="Image Type Properties">
  <ParamField path="code" type="string">
    A unique identifier for an image type. Allowed: "image", "thumbnail".
  </ParamField>

  <ParamField path="scope" type="string">
    The "Scope" property. Allowed: "global", "website", "store".
  </ParamField>
</Expandable>

### Image Mime Type

<Expandable title="Image Mime Type">
  <ParamField path="image/jpeg" type="string">
    ```json theme={null}
    { "mime" : "image/jpeg" }
    ```

    JPEG
  </ParamField>

  <ParamField path="image/gif" type="string">
    ```json theme={null}
    { "mime" : "image/gif" }
    ```

    GIF
  </ParamField>

  <ParamField path="image/png" type="string">
    ```json theme={null}
    { "mime" : "image/png" }
    ```

    PNG
  </ParamField>
</Expandable>

### Image Data

<Expandable title="Image Data">
  <ParamField path="file" type="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" }
    ```
  </ParamField>

  <ParamField path="position" type="integer">
    ```json theme={null}
    { "position" : 3 }
    ```
  </ParamField>

  <ParamField path="exclude" type="integer">
    ```json theme={null}
    { "exclude" : 1 }
    ```

    Allowed: "0" or "1".
  </ParamField>

  <ParamField path="url" type="string">
    ```json theme={null}
    { "url" : "https://shipstream.io/media/catalog/product/b/l/blackberry8100_2.jpg" }
    ```
  </ParamField>

  <ParamField path="types" type="array">
    ```json theme={null}
    { "types" : ["image", "thumbnail"] }
    ```

    Allowed: "image", "thumbnail".
  </ParamField>
</Expandable>