More Products

Magento (Adobe Commerce) product catalog API

Last updated: Oct-30-2024

You can use the Cloudinary product catalog API to programmatically link your Cloudinary media to your Magento (Adobe Commerce) 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.

On this page:

Configuration
Authentication
Endpoints
Get media for a specific SKU
Get media for multiple SKUs
Add media to a SKU
Add media for multiple SKUs
Remove media from a SKU

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:

In the Magento Admin Panel, select System > Integrations.
Select Add New Integration.
In the Integration Info tab, enter the relevant information as well as your username and password.
In the API tab, under Catalog > Inventory > Products select the options Mass Update Attributes, Edit Product Design and Edit Category Design to give the integration access to edit the product media.
Once added, select Activate and allow access to the selected APIs.
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:

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

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
GET`cloudinary/products/:sku/media`	Get media for a specific SKU
POST`cloudinary/products/media/get`	Get media for multiple SKUs
POST`cloudinary/products/:sku/media`	Add media to a SKU
POST`cloudinary/productGallery/addItems`	Add media for multiple SKUs

Tip

You can use GraphQL to retrieve specific product details from Cloudinary and utilize that information within Magento. For more information, see Magento (Adobe Commerce) GraphQL queries.

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

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

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.

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.

Parameter	Type	Description
sku	String	Required. The product SKU to remove media from.

Body parameters

Parameter	Type	Description
urls	Array	Required. An array of Cloudinary URLs to remove from a product.
delete_all_gallery	Boolean	Optional. Whether to delete all media from a product. Default: `false`.