API documentation

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": 2,
    "entries": [
      {
        "id": 1,
        "name": "Engine Oil",
        "description": null,
        "parent_id": null,
        "category_set_id": 1,
        "path": "default: Engine Oil",
        "category_set": {
          "id": 1,
          "name": "default"
        },
        "attribute_values": [
          {
              "attribute_definition_id": 25,
              "attribute_definition_code": "colour_hex",
              "data": "#000"
          },
          {
              "attribute_definition_id": 1,
              "attribute_definition_code": "colour",
              "data": "Green"
          }
        ],
        "media_items": [
          {
              "id": 255,
              "media_item_type": "ImageMediaItem",
              "url": "http://example.com/image-1",
              "description": "Sample description",
              "sort_order": 0,
              "is_primary": false,
              "is_uploaded": null,
              "asset_file_name": "photo-1513002749550-c59d786b8e6c",
              "public_url": "",
              "etag": "",
              "position": 0,
              "tag_list": [
                  "beautiful",
                  "t-shirt"
              ]
          }
        ]
      },
      {
        "id": 2,
        "name": "Transmission Oil",
        "description": null,
        "parent_id": null,
        "category_set_id": 1,
        "path": "default: Transmission Oil",
        "category_set": {
          "id": 1,
          "name": "default"
        },
        "attribute_values": [
          {
              "attribute_definition_id": 25,
              "attribute_definition_code": "colour_hex",
              "data": "#001"
          },
          {
              "attribute_definition_id": 1,
              "attribute_definition_code": "colour",
              "data": "Red"
          }
        ],
        "media_items": [
          {
              "id": 255,
              "media_item_type": "ImageMediaItem",
              "url": "http://example.com/image-2",
              "description": "Sample description",
              "sort_order": 0,
              "is_primary": false,
              "is_uploaded": null,
              "asset_file_name": "photo-1513002433fd4-c59d786b8e6c",
              "public_url": "",
              "etag": "",
              "position": 0,
              "tag_list": []
          }
        ]
      }
    ]
  }

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.
lang optional	Language code for translated value Validations: Must be a String
response_associated_fields optional	One of ‘attribute_values’, ‘association_attribute_values’, ‘media_items’. The information related to the category to be included in the category data response. Use comma to join multiple fields. Validations: Must be a String

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:
  {
    "category": {
        "path": "Test"
    }
  }

  Sample: create a category with attribute_values

  {
    "category": {
        "path": "Test",
        "attribute_values": [
          {
            "attribute_definition_id": 16,
            "attribute_definition_code": "description",
            "data": "Sample description..."
          }
        ]
    }
  }

  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.

  {
    "category": {
        "path": "Test",
        "attribute_values": [
          {
              "attribute_definition_id": 16,
              "attribute_definition_code": "img_desc",
              "data": {
                "associated_code": ["code_1", "code_2"]
              }
              "mode": "reset"
          }
      ]

    }
  }
  Sample: create a category with media items

  {
    "category": {
      "category_set": "Clothing",
      "path": "Shoes",
      "media_items": [
        {
          "media_item_type": "ImageMediaItem",
          "url": "https://www.gettyimages.com.au/gi-resources/images/500px/983801190.jpg",
          "description": "Description",
          "sort_order": 0,
          "is_primary": false,
          "is_uploaded": null,
          "tag_list": []
        }
      ]
    }
  }

  Sample: create a category with entity_identifiers

  {
    "category": {
        "path": "Test",
        "entity_identifiers": [
          {
            "key": "10000000001",
            "name": "Channel Name"
          },
          {
            "key": "20000000002",
            "name": "Channel Name"
          }
        ]
    }
  }

response:
  {
    "id": 3,
    "name": "Test",
    "description": null,
    "parent_id": null,
    "category_set_id": 1,
    "path": null,
    "category_set": {
      "id": 1,
      "name": "default"
    }
  }

Params

Param name	Description
category required	Validations: Must be a Hash
category[category_set] optional , nil allowed	Category set name. Default is ‘default’ category set. Ignored if parent_id is provided. Validations: Must be a String
category[path] optional , nil allowed	Full path of the category including all ancestors. Ignored if name is provided. Validations: Must be a String
category[name] optional , nil allowed	Category name Validations: Must be a String
category[parent_id] optional , nil allowed	Parent category id Validations: Must be a Integer
category[description] optional , nil allowed	Category description Validations: Must be a String
category[sort_order] optional , nil allowed	Sort order for category. Must be positive whole number Validations: Must be a Integer
category[attribute_values] optional , nil allowed	Attribute values assigned to the Category. Validations: Must be an array of any type
category[media_items] optional , nil allowed	Set media items to the entity (existing media items will be removed). Validations: Must be an Array of nested elements
category[media_items][media_item_type] optional , nil allowed	Validations: Must be one of: `ImageMediaItem`, `VideoMediaItem`, `FileMediaItem`.
category[media_items][url] optional , nil allowed	URL that stores the corresponding media item Validations: Must be a String
category[media_items][description] optional , nil allowed	Description for the media item Validations: Must be a String
category[media_items][sort_order_position] optional , nil allowed	The position of the media item. Non negative integer is supported Validations: Must be a Integer
category[media_items][is_primary] optional , nil allowed	Make this media item as primary Validations: Must be one of: `true`, `false`, `1`, `0`.
category[media_items][tag_list] optional , nil allowed	Tags for this media item Validations: Must be an array of String
category[media_items][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
category[media_items][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`.
category[media_items][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
category[media_items][processing_options][processed_tags] optional , nil allowed	The tags for the created media item. Validations: Must be an array of String

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:
  {
      "category": {
          "name": "Test Updated"
      }
  }

response:
  {
    "id": 3,
    "name": "Test Updated",
    "description": null,
    "parent_id": null,
    "category_set_id": 1,
    "path": "default: Test",
    "category_set": {
      "id": 1,
      "name": "default"
    }
  }

Params

Param name	Description
category required	Validations: Must be a Hash
category[category_set] optional , nil allowed	Category set name. Default is ‘default’ category set. Ignored if parent_id is provided. Validations: Must be a String
category[path] optional , nil allowed	Full path of the category including all ancestors. Ignored if name is provided. Validations: Must be a String
category[name] optional , nil allowed	Category name Validations: Must be a String
category[parent_id] optional , nil allowed	Parent category id Validations: Must be a Integer
category[description] optional , nil allowed	Category description Validations: Must be a String
category[sort_order] optional , nil allowed	Sort order for category. Must be positive whole number Validations: Must be a Integer
category[attribute_values] optional , nil allowed	Attribute values assigned to the Category. Validations: Must be an array of any type
category[media_items] optional , nil allowed	Set media items to the entity (existing media items will be removed). Validations: Must be an Array of nested elements
category[media_items][media_item_type] optional , nil allowed	Validations: Must be one of: `ImageMediaItem`, `VideoMediaItem`, `FileMediaItem`.
category[media_items][url] optional , nil allowed	URL that stores the corresponding media item Validations: Must be a String
category[media_items][description] optional , nil allowed	Description for the media item Validations: Must be a String
category[media_items][sort_order_position] optional , nil allowed	The position of the media item. Non negative integer is supported Validations: Must be a Integer
category[media_items][is_primary] optional , nil allowed	Make this media item as primary Validations: Must be one of: `true`, `false`, `1`, `0`.
category[media_items][tag_list] optional , nil allowed	Tags for this media item Validations: Must be an array of String
category[media_items][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
category[media_items][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`.
category[media_items][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
category[media_items][processing_options][processed_tags] optional , nil allowed	The tags for the created media item. Validations: Must be an array of String

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": 3
  }

Categories

Resource Representation¶ ↑

Supported Formats

GET /api/v2/categories
List categories

Supported Formats

Errors

Examples

Params

POST /api/v2/categories
Create an category

Supported Formats

Errors

Examples

Params

PUT /api/v2/categories/:id
Update an category

Supported Formats

Errors

Examples

Params

DELETE /api/v2/categories/:id
Delete an category

Supported Formats

Errors

Examples

Categories

Resource Representation¶ ↑

Supported Formats

GET /api/v2/categories List categories

Supported Formats

Errors

Examples

Params

POST /api/v2/categories Create an category

Supported Formats

Errors

Examples

Params

PUT /api/v2/categories/:id Update an category

Supported Formats

Errors

Examples

Params

DELETE /api/v2/categories/:id Delete an category

Supported Formats

Errors

Examples

GET /api/v2/categories
List categories

POST /api/v2/categories
Create an category

PUT /api/v2/categories/:id
Update an category

DELETE /api/v2/categories/:id
Delete an category