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:

  • photo (default)
  • rotate - usually associated with draggable 360° photo rotation. Used in conjunction with the frames property.
  • video - see the video property.
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 named my-image-name.jpg to the images/products subfolder 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:
  • first - insert or move the media item to the first position.
  • last - insert or move the media item to the last position.
  • before - insert or move the media item in front of another media item referenced by id (see below).
  • after - insert of move the media item after another media item reference by id (see below).
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:

  • true - will return only the primary media item for the product
  • false - will return all media items except the primary item for the product
type

Return media items by type:

  • photo
  • rotate
  • video


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.
  • limit - the number of results to return per page
  • page - the current page number
  • total - the total number of available results
  • totalPages - the total number of available pages of results
links
An object containing links to traverse available search results.
  • self - the URL for the current search.
  • previous - a URL for the previous results page, or null if there isn't one.
  • next - a URL for the next results page, or null if there isn't one


Example JSON response

In the example below you're able to see examples of different media types.

{
    "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:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string (e.g. error.not-unique if the alias supplied is already in use).


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
  • 400 may indicate that the ID was not provided.
  • 404 means Product or Media could not be found by the IDs provided.
  • 422 means the Media item could not be updated due to errors in the data.
context
  • parameters means the error is with the required id URL parameter.
  • data indicates an error within the Media object data.
errors

Contains an array of error objects, each will have the following properties:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string.


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
  • 400 may indicate that the ID was not provided, or the Media item could not be deleted for an unknown reason.
  • 404 indicates that the ID was provided, but the media item or product could not be found.