Media items

Resource Representation ↑

Example:
{
  "id": 14,
  "media_item_type": "ImageMediaItem",
  "url": "http://images.asos-media.com/inv/media/0/0/3/2/3882300/white/image2xxl.jpg",
  "description": "image description",
  "position": 1,
  "is_primary": true,
  "is_uploaded": null,
  "product_id": 9,
  "etag": "939e4638c1207407f8a2d332eb3fa8e4",
  "tag_list": [
    "lady's"
  ]
}

Supported Formats

json
>>>

GET /api/v2/media_items
List media_items

Supported Formats

json

Errors

Code Description
401 Unauthorized. Include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403 Forbidden. The request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404 Not Found. The requested resource could not be found.
422 Unprocessable Entity. The request was well-formed but was unable to be followed due to semantic errors.
500 Internal Server Error. An unexpected condition was encountered.

Examples

Response:
  {
    "page": 1,
    "per_page": 50,
    "total_pages": 1,
    "total_entries": 1,
    "entries": [
      {
        "id": 14,
        "media_item_type": "ImageMediaItem",
        "url": "http://images.asos-media.com/inv/media/0/0/3/2/3882300/white/image2xxl.jpg",
        "description": "image description",
        "sort_order": 1048576,
        "is_primary": true,
        "is_uploaded": null,
        "product_id": 9,
        "position": 1,
        "tag_list": [
          "lady's"
        ]
      }
    ]
  }

Params

Param name Description
per_page
optional

Number of objects in one response. Default is 50

Validations:

  • Must be a number.
page
optional

Page number. Default is 1

Validations:

  • Must be a number.
created_time_from
optional

ISO_8601 format 2016-05-30T05:13:26Z

Validations:

  • Must be a String
created_time_to
optional

ISO_8601 format 2016-05-30T05:13:26Z

Validations:

  • Must be a String
updated_time_from
optional

ISO_8601 format 2016-05-30T05:13:26Z

Validations:

  • Must be a String
updated_time_to
optional

ISO_8601 format 2016-05-30T05:13:26Z

Validations:

  • Must be a String
response_associated_fields
optional

One of ‘attribute_values, association_attribute_values’. The information related to the media item to be included in the media item data response. Use comma to join multiple fields.

Validations:

  • Must be a String
>>>

POST /api/v2/media_items
Create a media_item

Supported Formats

json

Errors

Code Description
401 Unauthorized. Include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403 Forbidden. The request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404 Not Found. The requested resource could not be found.
422 Unprocessable Entity. The request was well-formed but was unable to be followed due to semantic errors.
500 Internal Server Error. An unexpected condition was encountered.

Examples

request:
  {
      "media_item": {
          "media_item_type": "ImageMediaItem",
          "product_id": 9,
          "url": "http://images.asos-media.com/inv/media/0/0/3/2/3882300/white/image.jpg",
          "description": "image description",
          "position": 2,
          "is_primary": true,
          "tag_list": ["lady's"],
          "derived_media_items": [
          	{
          		"name": "crop",
          		"url": "http://images.asos-media.com/inv/media/0/0/3/2/3882300/white/image-crop.jpg"
          	}
          ],
          "attribute_values": [
            {
                "attribute_definition_id": 16,
                "attribute_definition_code": "img_desc",
                "data": "image description"
            }
        ]

      }
  }

Sample: create a media item for Npc Entity with npc entity code
{
  "media_item": {
      "media_item_type": "ImageMediaItem",
      "associated_type": "NpcEntity",
      "associated_code": "cotton",
      "url": "http://images.asos-media.com/inv/media/0/0/3/2/3882300/white/image.jpg",
      "description": "image description",
      "position": 2
      "is_primary": true,
      "tag_list": ["lady's"],
      "derived_media_items": [
        {
          "name": "crop",
          "url": "http://images.asos-media.com/inv/media/0/0/3/2/3882300/white/image-crop.jpg"
        }
      ]
  }
}

Sample: create a media item for Category with category id
{
  "media_item": {
      "media_item_type": "ImageMediaItem",
      "associated_type": "Category",
      "associated_id": 1,
      "url": "http://images.asos-media.com/inv/media/0/0/3/2/3882300/white/image.jpg",
      "description": "image description",
      "position": 2
      "is_primary": true,
      "tag_list": ["lady's"]
  }
}

Sample: reset multi shared reference association
Supported Mode:
- upsert: default
- reset: Delete all existing association for this attribute, and replace with the current one. Send empty array to remove all existing values.

{
  "media_item": {
      "media_item_type": "ImageMediaItem",
      "product_id": 9,
      "url": "http://images.asos-media.com/inv/media/0/0/3/2/3882300/white/image.jpg",
      "attribute_values": [
        {
            "attribute_definition_id": 16,
            "attribute_definition_code": "img_desc",
            "data": {
              "associated_code": ["code_1", "code_2"]
            }
            "mode": "reset"
        }
    ]

  }
}

response:
  {
    "id": 14,
    "media_item_type": "ImageMediaItem",
    "url": "http://images.asos-media.com/inv/media/0/0/3/2/3882300/white/image2xxl.jpg",
    "description": "image description",
    "sort_order": 1048576,
    "is_primary": true,
    "is_uploaded": null,
    "product_id": 9,
    "tag_list": [
      "lady's"
    ],
    "position": 2
  }

Params

Param name Description
media_item
required

Validations:

  • Must be a Hash
media_item[media_item_type]
optional , nil allowed

Validations:

  • Must be one of: ImageMediaItem, VideoMediaItem, FileMediaItem.
media_item[product_id]
optional , nil allowed

Product ID. Required if assigning media item to product and product_code is not provided

Validations:

  • Must be a Integer
media_item[product_code]
optional , nil allowed

Product Code. Required if assigning media item to product and product_id is not provided

Validations:

  • Must be a String
media_item[associated_type]
optional , nil allowed

Associated entity class name. Required if assigning media item to entity other than product like Npc Entity, Category

Validations:

  • Must be one of: NpcEntity, Category.
media_item[associated_id]
optional , nil allowed

Associated entity ID. Required if assigning media item to entity other than product and associated_code is not provided

Validations:

  • Must be a Integer
media_item[associated_code]
optional , nil allowed

Associated entity Code. Required if assigning media item to entity other than product and associated_id is not provided. Not supported for Category

Validations:

  • Must be a String
media_item[url]
required

URL that stores the corresponding media item

Validations:

  • Must be a String
media_item[description]
optional , nil allowed

Description for the media item

Validations:

  • Must be a String
media_item[sort_order_position]
optional , nil allowed

This field is deprecated. Please use position instead

Validations:

  • Must be a Integer
media_item[is_primary]
optional , nil allowed

Make this media item as primary

Validations:

  • Must be one of: true, false, 1, 0.
media_item[tag_list]
optional , nil allowed

Tags for this media item

Validations:

  • Must be an array of String
media_item[etag]
optional , nil allowed

ETag for the resource on the url

Validations:

  • Must be a String
media_item[processing_options]
optional , nil allowed

Options to perform extra image processing on the media item. This is applicable only when media_item_type is ‘ImageMediaItem’

Validations:

  • Must be a Hash
media_item[processing_options][apply_background]
optional , nil allowed

Setting this to true would result in a new media item created against the product with background applied. Removes transparency.

Validations:

  • Must be one of: true, false, 1, 0.
media_item[processing_options][background_colour]
optional , nil allowed

The colour name or a hex colour code for the background colour for the created media item. Defaults to white.

Validations:

  • Must be a String
media_item[processing_options][processed_tags]
optional , nil allowed

The tags for the created media item.

Validations:

  • Must be an array of String
media_item[derived_media_items]
optional , nil allowed

Transformations for this image

Validations:

  • Must be an Array of nested elements
media_item[derived_media_items][name]
optional , nil allowed

Name for the transformation

Validations:

  • Must be a String
media_item[derived_media_items][url]
optional , nil allowed

URL for the transformation

Validations:

  • Must be a String
media_item[position]
optional , nil allowed

Sort order value. Warning: Drag and drop sorting from UI might change the position you have set.

Validations:

  • Must be a Integer
media_item[attribute_values]
optional , nil allowed

Attribute values assigned to the Media Item.

Validations:

  • Must be an array of any type
>>>

POST /api/v2/media_items/upload
Create a media_item via binary upload. The request is a multipart/form-data and the response is json like other API calls.

Supported Formats

json

Errors

Code Description
401 Unauthorized. Include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403 Forbidden. The request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404 Not Found. The requested resource could not be found.
422 Unprocessable Entity. The request was well-formed but was unable to be followed due to semantic errors.
500 Internal Server Error. An unexpected condition was encountered.

Examples

request:
  curl --request POST         --url https://product.commerceconnect.co/api/v2/media_items/upload         --header 'authorization: Token token=YOUR_TOKEN,email=YOUR_EMAIL'         --header 'content-type: multipart/form-data;'         --form 'image_media_item[asset]=@test.png'         --form product_id=257         --form 'image_media_item[description]=Test'         --form 'image_media_item[sort_order_position]=1'         --form 'image_media_item[is_primary]=true'         --form 'image_media_item[tag_list]=test_tag'         --form 'image_media_item[position]=100'

response:
  {
    "id": 968,
    "media_item_type": "ImageMediaItem",
    "url": "http://s3-ap-southeast-2.amazonaws.com/fusionfactory.commerceconnect.localming6.local/pim_media/000/000/968/test.png?1487740669",
    "description": "Test",
    "sort_order": 7340032,
    "is_primary": true,
    "is_uploaded": true,
    "product_id": 257,
    "asset_file_name": "test.png",
    "position": 100,
    "tag_list": [
      "test_tag"
    ]
  }
>>>

PUT /api/v2/media_items/:id
Update a media_item

Supported Formats

json

Errors

Code Description
401 Unauthorized. Include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403 Forbidden. The request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404 Not Found. The requested resource could not be found.
422 Unprocessable Entity. The request was well-formed but was unable to be followed due to semantic errors.
500 Internal Server Error. An unexpected condition was encountered.

Examples

request:
  {
      "media_item": {
          "url": "http://images.asos-media.com/inv/media/0/0/3/2/3882300/white/image3xxl.jpg"
      }
  }

response:
  {
    "id": 14,
    "media_item_type": "ImageMediaItem",
    "url": "http://images.asos-media.com/inv/media/0/0/3/2/3882300/white/image3xxl.jpg",
    "description": "image description",
    "sort_order": 1048576,
    "is_primary": true,
    "is_uploaded": null,
    "product_id": 9,
    "position": 1,
    "tag_list": [
      "lady's"
    ]
  }

Params

Param name Description
media_item
required

Validations:

  • Must be a Hash
media_item[media_item_type]
optional , nil allowed

Validations:

  • Must be one of: ImageMediaItem, VideoMediaItem, FileMediaItem.
media_item[product_id]
optional , nil allowed

Product ID. Required if assigning media item to product and product_code is not provided

Validations:

  • Must be a Integer
media_item[product_code]
optional , nil allowed

Product Code. Required if assigning media item to product and product_id is not provided

Validations:

  • Must be a String
media_item[associated_type]
optional , nil allowed

Associated entity class name. Required if assigning media item to entity other than product like Npc Entity, Category

Validations:

  • Must be one of: NpcEntity, Category.
media_item[associated_id]
optional , nil allowed

Associated entity ID. Required if assigning media item to entity other than product and associated_code is not provided

Validations:

  • Must be a Integer
media_item[associated_code]
optional , nil allowed

Associated entity Code. Required if assigning media item to entity other than product and associated_id is not provided. Not supported for Category

Validations:

  • Must be a String
media_item[url]
optional

URL that stores the corresponding media item

Validations:

  • Must be a String
media_item[description]
optional , nil allowed

Description for the media item

Validations:

  • Must be a String
media_item[sort_order_position]
optional , nil allowed

This field is deprecated. Please use position instead

Validations:

  • Must be a Integer
media_item[is_primary]
optional , nil allowed

Make this media item as primary

Validations:

  • Must be one of: true, false, 1, 0.
media_item[tag_list]
optional , nil allowed

Tags for this media item

Validations:

  • Must be an array of String
media_item[etag]
optional , nil allowed

ETag for the resource on the url

Validations:

  • Must be a String
media_item[processing_options]
optional , nil allowed

Options to perform extra image processing on the media item. This is applicable only when media_item_type is ‘ImageMediaItem’

Validations:

  • Must be a Hash
media_item[processing_options][apply_background]
optional , nil allowed

Setting this to true would result in a new media item created against the product with background applied. Removes transparency.

Validations:

  • Must be one of: true, false, 1, 0.
media_item[processing_options][background_colour]
optional , nil allowed

The colour name or a hex colour code for the background colour for the created media item. Defaults to white.

Validations:

  • Must be a String
media_item[processing_options][processed_tags]
optional , nil allowed

The tags for the created media item.

Validations:

  • Must be an array of String
media_item[derived_media_items]
optional , nil allowed

Transformations for this image

Validations:

  • Must be an Array of nested elements
media_item[derived_media_items][name]
optional , nil allowed

Name for the transformation

Validations:

  • Must be a String
media_item[derived_media_items][url]
optional , nil allowed

URL for the transformation

Validations:

  • Must be a String
media_item[position]
optional , nil allowed

Sort order value. Warning: Drag and drop sorting from UI might change the position you have set.

Validations:

  • Must be a Integer
media_item[attribute_values]
optional , nil allowed

Attribute values assigned to the Media Item.

Validations:

  • Must be an array of any type
>>>

DELETE /api/v2/media_items/:id
Delete a media_item

Supported Formats

json

Errors

Code Description
401 Unauthorized. Include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403 Forbidden. The request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404 Not Found. The requested resource could not be found.
422 Unprocessable Entity. The request was well-formed but was unable to be followed due to semantic errors.
500 Internal Server Error. An unexpected condition was encountered.

Examples

response:
  {
    "id": 14
  }
>>>

POST /api/v2/media_items/delete_by_filter
Delete media_items with specified tags in the given product

Supported Formats

json

Errors

Code Description
401 Unauthorized. Include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403 Forbidden. The request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404 Not Found. The requested resource could not be found.
422 Unprocessable Entity. The request was well-formed but was unable to be followed due to semantic errors.
500 Internal Server Error. An unexpected condition was encountered.

Examples

request:
  {
    "product_id": 9,
    "tag_list": [
      "lady's"
    ]
  }
response:
  {
    "id": 14
  }