Magento product catalog API

You can use the Cloudinary product catalog API to programmatically link your Cloudinary media to your products by providing the URL and product SKU. For example, if you have existing media assets with Cloudinary, you can use the product catalog API to add these to your product listing pages in bulk. You can also retrieve all media linked to a specific SKU or set of SKUs.

Configuration

To configure the API, ensure you have the Cloudinary plugin installed. The API is built on top of the Magento 2 REST API and therefore you’ll need to create a new integration in order to allow access to edit the product catalog via the API.

To create the integration:

  1. In the Magento Admin Panel, select System > Integrations.
  2. Select Add New Integration.
  3. In the Integration Info tab, enter the relevant information as well as your username and password.
  4. In the API tab, under Catalog > Inventory > Products select Edit Product Design to give the integration access to edit the product media.
  5. Once added, select Activate and allow access to the selected APIs.
  6. Retrieve your Access Token, you will use this to authenticate your requests to the API.

Authentication

The API uses Bearer Authentication. Send the token you retrieved when creating your new integration. For example:

Copy to clipboard
Authorization: Bearer abc123mytoken123

The Content-Type header is also required for all requests. This will always be application/json. For example:

Copy to clipboard
Content-Type: application/json

Endpoints

As the API is built on top of the Magento REST API, the base URL is the same:

https://{MAGENTO_HOST_OR_IP}/{MAGENTO_BASE_INSTALL_DIR}/rest/V1


The Cloudinary plugin creates four new endpoints:

Method Description
GETcloudinary/products/:sku/media Get media for a specific SKU
POSTcloudinary/products/media/get Get media for multiple SKUs
POSTcloudinary/products/:sku/media Add media to a SKU
POSTcloudinary/productGallery/addItems Add media for multiple SKUs


Get media for a specific SKU

Lists all media asset URLs for the specified SKU.

Syntax

GET /cloudinary/products/:sku/media

Parameters

Parameter Type Description
sku String Required. The product SKU to return media for.

Example

Get media assets for product SKU "my-product-sku":

Copy to clipboard
curl https://my-magento-shop.com/rest/V1/cloudinary/products/my-product-sku/media \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access-token>' \

Sample response

The response is returned as stringified JSON:

Copy to clipboard
"{\"data\":{\"image\":\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/c_lpad,d_sample.jpg,dpr_2.0,f_auto,q_auto\\/v1\\/media\\/catalog\\/product\\/w\\/t\\/my-product-sku_main_1.jpg\",\"small_image\":\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/c_lpad,d_sample.jpg,dpr_2.0,f_auto,q_auto\\/v1\\/media\\/catalog\\/product\\/w\\/t\\/my-product-sku_main_1.jpg\",\"thumbnail\":\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/c_lpad,d_sample.jpg,dpr_2.0,f_auto,q_auto\\/v1\\/media\\/catalog\\/product\\/w\\/t\\/my-product-sku_main_1.jpg\",\"media_gallery\":[\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/c_lpad,d_sample.jpg,dpr_2.0,f_auto,q_auto\\/v1\\/media\\/catalog\\/product\\/w\\/t\\/my-product-sku_main_1.jpg\"]}}"

Get media for multiple SKUs

Lists all media asset URLs for the specified SKUs.

Syntax

POST /cloudinary/products/media/get

Parameters

Parameter Type Description
skus Array Required. An array of product SKUs to return media for.

Example

Get media assets for product SKUs "my-product-sku1" and "my-product-sku2":

Copy to clipboard
curl  -X POST 'https://my-magento-shop.com/rest/V1/cloudinary/products/media/get' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access-token>' \
-d '{
    "skus": ["my-product-sku1","my-product-sku2"]
}'

Sample response

The response is returned as stringified JSON:

Copy to clipboard
"{\"data\":{\"my-product-sku1\":{\"image\":\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/c_lpad,d_sample.jpg,dpr_2.0,f_auto,q_auto\\/v1\\/media\\/catalog\\/product\\/w\\/t\\/my-product-sku_main_1.jpg\",\"small_image\":\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/c_lpad,d_sample.jpg,dpr_2.0,f_auto,q_auto\\/v1\\/media\\/catalog\\/product\\/w\\/t\\/my-product-sku_main_1.jpg\",\"thumbnail\":\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/c_lpad,d_sample.jpg,dpr_2.0,f_auto,q_auto\\/v1\\/media\\/catalog\\/product\\/w\\/t\\/my-product-sku_main_1.jpg\",\"media_gallery\":[\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/c_lpad,d_sample.jpg,dpr_2.0,f_auto,q_auto\\/v1\\/media\\/catalog\\/product\\/w\\/t\\/my-product-sku_main_1.jpg\"]},\"my-product-sku2\":{\"image\":\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/c_lpad,d_sample.jpg,dpr_2.0,f_auto,q_auto\\/v1\\/media\\/catalog\\/product\\/w\\/t\\/my-product-sku_main_1.jpg\",\"small_image\":\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/c_lpad,d_sample.jpg,dpr_2.0,f_auto,q_auto\\/v1\\/media\\/catalog\\/product\\/w\\/t\\/my-product-sku_main_1.jpg\",\"thumbnail\":\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/c_lpad,d_sample.jpg,dpr_2.0,f_auto,q_auto\\/v1\\/media\\/catalog\\/product\\/w\\/t\\/my-product-sku_main_1.jpg\",\"media_gallery\":[\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/c_lpad,d_sample.jpg,dpr_2.0,f_auto,q_auto\\/v1\\/media\\/catalog\\/product\\/w\\/t\\/my-product-sku_main_1.jpg\"]}}}"

Add media to a SKU

Adds media asset URLs to the specified SKU.

Syntax

POST /cloudinary/products/:sku/media

Query parameters

Parameter Type Description
sku String Required. The product SKU to return media for.

Body parameters

Parameter Type Description
urls Array Required. An array of URL objects, each containing Cloudinary URLs (and optionally public IDs) to add to a product.

URL object parameters

Parameter Type Description
url String Required. The Cloudinary URL of the media to be added to a product.
publicId String Optional. The Cloudinary Public ID of the media to be added to a product. Only required if the Cloudinary URL does not contain a version.
roles String or Array Optional. The product image role(s) of the image to be added to a product. Can be either an array of strings or a single string containing a comma separated list.
label String Optional. The label associated with the image. Used as the alt text.
disabled Boolean Optional. Whether the image should be hidden from the product page. Default: false.
cldspinset String The tag name for the images to be used in a spinset.

Example

Add media assets for product SKU "my-product-sku":

Copy to clipboard
curl  -X POST 'https://my-magento-shop.com/rest/V1/cloudinary/products/my-product-sku/media' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access-token>' \
-d '{
    "urls": [
        {
            "url": "https://res.cloudinary.com/myMagentoCloud/image/upload/e_blur:100,r_16/a_178/v1523871670/sample.jpg",
            "publicId": null,
            "disabled": 0,
            "label": "Some Alt Text"
        },
        {
            "publicId": null,
            "disabled": 0,
            "label": "Some Alt Text",
            "cldspinset": "my-spinset-1"
        },
        {
            "url": "https://res.cloudinary.com/myMagentoCloud/image/upload/e_blur:100,r_16/a_178/v1523871670/sample.jpg",
            "publicId": null,
            "disabled": 0,
            "label": "Some Alt Text",
            "cldspinset": "my-spinset-2"
        },
        {
            "url": "https://res.cloudinary.com/myMagentoCloud/video/upload/v1563701653/sample.mp4",
            "publicId": null
        }
    ]
}'

Sample response

The response is returned as stringified JSON:

Copy to clipboard
"{\"passed\":4,\"failed\":{\"count\":0,\"urls\":[]},\"message\":\"All items have been added to queue.\"}"

Add media for multiple SKUs

Adds media asset URLs to multiple SKUs.

Syntax

POST /cloudinary/productGallery/addItems

Parameters

Parameter Type Description
items Array Required. An array of items objects, each containing the SKU to add media to and the Cloudinary URLs (plus optionally public IDs) to add to the product.

Items object parameters

Parameter Type Description
sku String Required. The product SKU to return media for.
url String Required. The Cloudinary URL of the media to be added to a product.
publicId String Optional. The Cloudinary Public ID of the media to be added to a product. Only required if the Cloudinary URL does not contain a version.
roles String or Array Optional. The product image role(s) of the image to be added to a product. Can be either an array of strings or a single string containing a comma separated list.
label String Optional. The label associated with the image. Used as the alt text.
disabled Boolean Optional. Whether the image should be hidden from the product page. Default: false.
cldspinset String Optional. The tag name for the images to be used in a spinset.

Example

Add media assets for product SKUs "my-product-sku1" and "my-product-sku2":

Copy to clipboard
curl  -X POST 'https://my-magento-shop.com/rest/V1/cloudinary/productGallery/addItems' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access-token>' \
-d '{
    "items": [
        {
            "url": "https://res.cloudinary.com/myMagentoCloud/image/upload/e_blur:100,r_16/a_178/v1523871670/sample.jpg",
            "sku": "my-product-sku1",
            "publicId": null,
            "disabled": 0,
            "label": "Some Alt Text"
        },
        {
            "url": "https://res.cloudinary.com/myMagentoCloud/video/upload/v1563701653/sample.mp4",
            "sku": "my-product-sku2",
            "publicId": null
        }
    ]
}'

Sample response

The response is returned as stringified JSON:

Copy to clipboard
"{\"errors\":0,\"items\":[{\"url\":\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/image\\/upload\\/e_blur:100,r_16\\/a_178\\/v1523871670\\/sample.jpg\",\"sku\":\"my-product-sku1\",\"publicId\":null,\"disabled\":0,\"label\":\"Some Alt Text\",\"error\":0,\"message\":\"The item was added to the queue.\"},{\"url\":\"https:\\/\\/res.cloudinary.com\\/myMagentoCloud\\/video\\/upload\\/v1563701653\\/sample.mp4\",\"sku\":\"my-product-sku2\",\"publicId\":null,\"error\":0,\"message\":\"The item was added to the queue.\"}],\"message\":\"All items have been added to queue.\"}"

✔️ Feedback sent!

Rate this page: