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.

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

Syntax

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 one new endpoint, which you can use the HTTP POST method to send your requests to:

https://{MAGENTO_HOST_OR_IP}/{MAGENTO_BASE_INSTALL_DIR}/rest/V1/cloudinary/products/{SKU}/media


Include the product SKU in the URL, this is the product you want to add your media to.

Send the Cloudinary URLs for the media you want to add in the JSON request body.

Parameters

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

URL object parameters

Parameter Type Description
url String The Cloudinary URL of the media to be added to a product. Required.
publicId String The Cloudinary Public ID of the media to be added to a product. Only required if the Cloudinary URL does not contain a version. Optional.
roles String or Array 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. Optional.
label String The label associated with the image. Used as the alt text. Optional.
disabled Boolean Whether the image should be hidden from the product page. Default: false. Optional.

Examples

The examples are all POST requests to the following endpoint:

https://amazing-magento-shop.com/rest/V1/cloudinary/products/amazing-product-sku/media


Example of adding a sample image and video to the product SKU “amazing-product-sku”:

Copy to clipboard
{
   "urls": [
    {
       "url": "https://res.cloudinary.com/demo/image/upload/v123/sample.jpg"
    },
    {
       "url": "https://res.cloudinary.com/demo/video/upload/v123/dog.mp4"
    }
   ]
}

Example of adding a sample image and video to the same SKU with no version provided:

Copy to clipboard
{
   "urls": [
    {
       "url": "https://res.cloudinary.com/demo/image/upload/sample.jpg",
       "publicId": "sample"
    },
    {
       "url": "https://res.cloudinary.com/demo/video/upload/dog.mp4",
       "publicId": "dog"
    }
   ]
}

Example of adding a sample image to the product SKU “amazing-product-sku” with a label, and the roles: image, small_image and thumbnail:

Copy to clipboard
{
   "urls": [
    {
       "url": "https://res.cloudinary.com/demo/image/upload/v123/sample.jpg",
       "roles": ["image","small_image","thumbnail"],
       "label": "Amazing Product",
       "disabled": false
    }
   ]
}

Sample Response

Copy to clipboard
"{\"passed\":2,\"failed\":{\"count\":0,\"urls\":[]}}"

✔️ Feedback sent!