Product Media API v2
The Product Media resource lets you get, create, update or remove media associated with a product from an Account's product catalogue.
Scopes
Access to the Product Media API requires that the client have the following scopes granted:
products- Permits write access to add, update or remove product media.products.readonly- Read only access to search or get product media data.
The Product Media object
Product may have a mixture of photos, videos and 360 degree media items.
createdBy
read-only
An integer representing the Contact ID who created the Media item. This may be set to null if the Product was created by an App or via import.
|
createdOn
read-only
The date and time the media item was created. |
description
An optional short description describing the media item up to 200 characters long. |
frames
An array containing URLs to images within the Media Library may be a JPEG,
GIF, or PNG file up to 20MB in
size each.
Evance requires images to be imported into the Media Library. If you supply each image as a Data URI, or an external URL, Evance will import the image into the Media Library and an Evance CDN URL will be returned. The frames property is applicable to media items with a type of
rotate only.
See Importing Media Files below. |
id
read-only
An unsigned 64-bit integer, which is unique across all Product Media and all Evance Accounts. |
image
The URL to an image in the Media Library may be a JPEG, GIF,
or PNG file up to 20MB in size.
Evance requires images to be imported into the Media Library. If you supply the image as a Data URI, or an external URL, Evance will import the image into the Media Library and an Evance CDN URL will be returned. The image property is required for all media types. See Importing Media Files below. |
isPrimary
Boolean, indicates whether the media item is used as the primary image for the Product. The primary media item is used as the Products thumbnail at Category level. A Product may only have one primary media item. |
modifiedBy
read-only
An integer representing the Contact ID who last modified the Media item. This may be set to null if the Product was created by an App or via import.
|
modifiedOn
read-only
The date and time the media item was last modified. |
productId
read-only
An unsigned 64-bit integer representing the Product the Media item is associated with. |
sequence
Indicates the display position of the media item. The sequence of media items starts from 1 (the first media item). You may supply the sequence when adding or updating media items as an integer or as an object containing placement and
idproperties (see Sequencing Media Items below).
If omitted when inserting media, the new media item will be positioned last in the sequence. |
title
An optional title up to 80 characters long for the media item may be displayed or used as an alt attribute.
|
type
Type affects the media requirements and display. The type may be one of the following:
|
video
The URL to a YouTube, Vimeo video or an MP4 file within the Media Library up
to 250MB in size.
If you supply the video as a Data URI, or an external URL (except YouTube or Vimeo URLs), Evance will import the video into the Media Library and an Evance CDN URL will be returned. A video URL is required if the type is set to
video and may be ignored or set to null for alternative
types of media.
See Importing Media Files below. |
Importing Media files
Importing new files for
image,
video and
frames properties may be done using one of the following methods:
-
Content URI
Upload files to the Media Library manually through the Evance admin panel, then reference their location using a Content URI. For example, uploading a file namedmy-image-name.jpgto theimages/productssubfolder in the Media Library is referenced as~/content/images/products/my-image-name.jpg. Whilst this may be appropriate when importing Products via CSV, it may not be desirable for API integrations. -
External URLs
With the exception of YouTube and Vimeo URLs for video content, Evance will import file data from external URLs (http or https) into the Media Library. The file will be placed in an directory in the Media Library, which is calculated based on the URL and the mime type of the file. -
Data URIs
You can provide base64 encoded binary file data as a Data URI. Evance will calculate the directory within the Media Library based on the mime type of the file and the filename will be based on an md5 of the file contents.
When importing External URLs or Data URIs, you may want greater control over the resulting filename and location within the
Media Library. Supply your data within an object consisting of
src,
filename and
directory properties:
src
Required. May be either an absolute External URL, or a Data URI. |
filename
Optional, allows you to set a preferred filename and extension for the media item. For example my-file-name.png. The file name should not include spaces or special characters. The extension must be appropriate to the mime type. |
directory
Optional, allows you to set a preferred directory within the Media Library and must be a valid Content URI starting with ~/content. |
Example
The example below highlights how to specify both a filename and directory for a media image imported using a Data URI.
{
"data": {
"image": {
"src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
"filename": "my-image-name.png",
"directory": "˜/content/images/products"
}
}
}
If the filename already exists within the directory supplied, the import may be ignored as Evance may assume the file already
exists.
Sequencing Media items
The position of media items is represented by the sequence property. When importing
data you may adjust the sequence of media files by supplying either an integer (starting from 1) or a position object
containing placement and id properties.
When supplying an integer, existing media items with a sequence greater than or equal to the sequence supplied will increment by one. If you supply a sequence number greater than the current number of media items, your media file will be positioned last and the appropriate sequence number will be recalculated and returned as part of the response.
Alternatively, you may supply a position object consisting of the following properties:
placement
May be one of the following:
|
id
Required when placement is either before or
after. Represents the ID of another Media item for the same Product. |
Example
The example below shows a request to position the media item before another media item with ID 1234.
{
"data": {
"sequence": {
"placement": "before",
"id": 1234
}
}
}
List/search Media for a given Product
GET
/api/v2/products/{productId}/media.json
Get or search for one or more media items associated with a Product using a range of accepted query parameters.
URL parameters
productId
required
The product ID is required. |
Query parameters
id:in
Return media items for a product by a comma-separated list of IDs. |
id:min
Return media items with an ID greater than or equal to that specified. |
id:max
Return media items with an ID less than or equal to that specified. |
id:after
Return media items with an ID greater than that specified. |
id:before
Return media items with an ID less than that specified. |
isPrimary
Return media items by their primary status:
|
type
Return media items by type:
|
JSON response
Evance will return a JSON object containing the following properties:
success
A successful search request containing zero or more results will always return a true value.
|
status
An integer matching the HTTP response code. A successful request will have a status of 200.
|
data
An array containing zero or more Product Media data objects. |
pagination
Search results include a pagination object contain information about the current page, total pages, the limit per page and the total number of results available.
|
links
An object containing links to traverse available search results.
|
Example JSON response
{
"success": true,
"status": 200,
"data": [
{
"id": 48646,
"productId": 3066,
"type": "photo",
"isPrimary": true,
"image": "https://cdn.evance.me/portal/web/0/content/images/be05aa4b29f41eb94c6f4bb5a36370be.jpg",
"video": null,
"title": null,
"description": null,
"sequence": 1,
"createdOn": "2022-05-21T15:54:05+00:00",
"createdBy": null,
"modifiedOn": "2022-05-21T15:54:05+00:00",
"modifiedBy": null
},
{
"id": 48649,
"productId": 3066,
"type": "video",
"isPrimary": false,
"image": "https://cdn.evance.me/portal/web/0/content/images/be05aa4b29f41eb94c6f4bb5a36370be.jpg",
"video": "https://www.youtube.com/watch?v=ZpZ5Wu5Myeo",
"title": null,
"description": null,
"sequence": 2,
"createdOn": "2022-05-21T15:55:05+00:00",
"createdBy": null,
"modifiedOn": "2022-05-21T15:55:05+00:00",
"modifiedBy": null
},
{
"id": 48651,
"productId": 3066,
"type": "rotate",
"isPrimary": false,
"image": "https://cdn.evance.me/portal/web/0/content/images/be05aa4b29f41eb94c6f4bb5a36370be.jpg",
"video": null,
"title": null,
"description": null,
"sequence": 3,
"createdOn": "2022-05-21T15:56:05+00:00",
"createdBy": null,
"modifiedOn": "2022-05-21T15:56:05+00:00",
"modifiedBy": null,
"frames": [
"https://cdn.evance.me/portal/web/0/content/images/be05aa4-frame-01.jpg",
"https://cdn.evance.me/portal/web/0/content/images/be05aa4-frame-02.jpg",
"https://cdn.evance.me/portal/web/0/content/images/be05aa4-frame-03.jpg",
"https://cdn.evance.me/portal/web/0/content/images/be05aa4-frame-04.jpg",
"https://cdn.evance.me/portal/web/0/content/images/be05aa4-frame-05.jpg"
]
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
},
"links": {
"self": "https://examples.evance.me/api/v2/products/3066/media.json",
"previous": null,
"next": null
}
}
Get a single Product Media item
GET
/api/v2/products/{productId}/media/{id}.json
Retrieve a single Product Media item using its ID.
URL parameters
id
required
The ID of the Product Media item is supplied as a path parameter. |
productId
required
The ID of the Product is supplied as a path parameter. |
Response
Returns an object with the following properties:
success
A boolean where a value of true represents a successful request.
|
status
The HTTP status code e.g. 200 for a successful request.
|
data
Contains the Product Media object. |
Example JSON response
{
"success": true,
"status": 200,
"data": {
"id": 48646,
"productId": 3066,
"type": "photo",
"isPrimary": true,
"image": "https://cdn.evance.me/portal/web/0/content/images/be05aa4b29f41eb94c6f4bb5a36370be.jpg",
"video": null,
"title": null,
"description": null,
"sequence": 1,
"createdOn": "2022-05-21T15:54:05+00:00",
"createdBy": null,
"modifiedOn": "2022-05-21T15:54:05+00:00",
"modifiedBy": null
}
}
Add a Product Media item
POST
/api/v2/products/{productId}/media.json
Add a Media item to a Product.
Requires the products OAuth scope.
URL parameters
productId
required
The ID of the Product is supplied as a path parameter. |
Request body
Your request body must contain an object including:
data
required
Containing a Product Media object. |
Example: minimum requirements
The minimum requirement for a media item is an image value. In the example
below we're supplying an image using a Data URI.
{
"data": {
"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
}
}
Importing media using a Data URI will result in a new filename based on the md5 of the file
contents and it's location in the Media Library will be based on the file's mime type. However, this may not be desirable
if you wish to maintain searchable filenames. You can define your preferred filename and/or directory for your Data URI
using a Content URI request object, which consists of a src,
filename and
directory property (as illustrated below).
{
"data": {
"image": {
"src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
"filename": "my-image-name.png",
"directory": "˜/content/images/products"
}
}
}
The directory, if supplied, must be a valid Content URI starting with
~/content. If the directory is not supplied it will be calculated based on the file's
mime type.
Success response
If the Product Media was created successfully you should receive a response with a 201 status
code:
success
A boolean where a value of true means the Media was created successfully.
|
status
The HTTP status code e.g. 201 means the Media was created successfully. |
data
Contains the Product Media object you created including its new id and any URLs to imported
image,
video or
frames.
|
Error responses
If the Media item could not be created you will encounter a response with a 422 status code:
success
A boolean where a value of false means the Media item could not be created.
|
status
A response code of 422 means the Media item could not be created and you should
check the errors property for further information. |
context
The context property indicates where the error occurred. For a 422 error this
will typically contain a value of data, indicating that there was an error
with the data object supplied. |
errors
Contains an array of error objects, each will have the following properties:
|
Update a Product Media item
PUT
/api/v2/products/{productId}/media/{id}.json
Update an existing Product Media item by its ID.
Requires the products OAuth scope.
URL parameters
id
required
The ID of your Product Media object |
productId
required
The ID of your Product object |
Request body
Your request body must contain an object including:
data
required
Containing updates to your Product Media object. |
Example JSON request
To update a Product Media item you must PUT JSON to this resource within a data object.
You do not need to supply all properties and may choose to only supply properties that require modifying.
{
"data": {
"image": "https://url-to-import.com/example-image.jpg,
"title": "Example image"
}
}
Success response
If the Media item was updated successfully you should receive a response with a 200 status
code:
success
A boolean where a value of true means the object was saved successfully.
|
status
The HTTP status code e.g. 200 means the object was updated successfully. |
data
Contains the Product Media object you updated. |
Error responses
If the Media could not be updated you will encounter a response with either a 400, 404 or
422status code:
success
A boolean where a value of false means the object could not be updated.
|
status
|
context
|
errors
Contains an array of error objects, each will have the following properties:
|
Delete a Product Media item
DELETE
/api/v2/products/{productId}/media/{id}.json
Delete a Product Media item within your product catalogue by its ID.
Requires the products OAuth scope.
URL parameters
id
required
The ID of your Product Media object |
productId
required
The ID of your Product object |
Request body
Does not require a payload
Success response
If the Media item was deleted successfully you should receive a response with a 204 status
code and no body.
Error responses
If the Media item could not be deleted you may encounter a response with a 400, or 404 status
code:
success
A boolean where a value of false means the Media item could not be deleted.
|
status
|