Plytixconnector v1

Add a new sub-category under an existing category

Parameters

Deletes a category and all its subcategories.

WARNING All subcategories will be removed too.

If you want to preserve some of the subcategories, it's mandatory you move them before deleting parent category.

A 204 response is returned upon success.

If category to be deleted, or any of its subcategories, is used as root category in some E-Catalog a 409 response code will be returned. Please look at https://help.plytix.com/designing-e-catalogs for more information on E-Catalogs and filters

Parameters

Get one asset from this account

Parameters

Gets a product's asset by id

Parameters

Using this verb you can change some of the properties of any category.

Allowed properties:

Note: parent_id and sort_children are not allowed in the same request.

Moving Categories

Convert to root category (a.k.a first level categories)

You must issue a patch request to https://pim.plytix.com/api/v1/categories/file/categoryId (see examples) specifiying parent_id as empty string, i.e. {"parent_id": ""}

Move as subcategory of another category

You must issue a patch request to https://pim.plytix.com/api/v1/categories/file/categoryId (see examples) specifiying parent_id as new parent category id, i.e. {"parent_id": "new parent category here"}

Sorting Categories

Sorting Root Categories

When patching root categories (a.k.a first level categories) only reorder is allowed and must be done under the special endpoint https://pim.plytix.com/api/v1/categories/file/root, 200 status code is returned upon successful response and empty data array is returned.

Sorting Subcategories

A patch request must be issued to parent ID category including in its body a dictionary with ALL subcategories in desired order, you are not allowed to make partial orders or add new categories or this operations will return 422 error code.

{ 'sort_children': [ subcategory_ids ]

Parameters

Modifies attributes from asset and leaves the rest unchanged.

Current version supports the modification of the following fields:

Parameters

Removes an asset from this account

Parameters

Parameters

Removes relationship between a product and an asset. Asset is not deleted

Parameters

Upload a new asset to your account

There are two methods for uploading assets to the system:

• By specifying an url

• By supplying the content of the asset

Both methods are described in this document

Upload an asset by url

This method allows you to specify an url, the system then tries to download it and
add it to your account.
There are a few issues that must be taken into account:

• url must be publicly accessible

• file must be one of the supported file types

If no filename is specified, the filename of the asset in the url will be used.

__NOTE__: This system __DOES NOT__ convert files between formats and if different
file format of the requested url and filename are used there could be problems

Upload an asset by filename and content

This method allows you to upload an asset by sending its content (base64 format) in the body of the request.

__NOTE__: Content field must contain only image data, stripping data:image/XXX;base64,

Parameters

Parameters

Filter on available file categories by multiple criteria

Filter structure and format is described under Resources section in this guide

Current version of the API supports the following set of fields

Restrictions

• Search requests

• Search filters MUST include all necessary columns (except ID which is returned by default). If an attribute is not explicitly requested it won’t be returned by the API.

Available attributes can be obtained by means of the available https://pim.plytix.com/api/v1/filters/ endpoint. “key” value is what MUST be used in requests.
Requesting non-existing attributes will return a 422 error code
You are allowed to sort by columns not included in “attributes” field, however this attribute won’t be returned

• Search filters will return a 422 error code if any of the following conditions is met:

a) Field does not exist
b) Operator is not allowed for the given field (available operators and fields can be obtained using /filters/{item} endpoint)
c) Value has no meaning for the given operator. The arity of available operators can be found in API documentation

• Pagination: the number of items that can be requested (pagination.page_size) is limited to a maximum 100 items.

A 422 code will be returned from API if this limit is exceeded. If pagination is omitted 25 items of the first page will be returned

Parameters

Filter assets by multiple criteria

Filter structure and format is described under Resources section in this guide

Parameters

Get all assets related to this product

Parameters

Link an existing asset to an existing media attribute of a product.

All parameters are mandatory:

• id of the product.

• id of the asset.

• label of the attribute

Unknown parameters will be ignored from request data.

Note: This method does not allow the creation of new attributes, nor upload of new assets to your PIM.

Assets can be linked to product thumbnail and product custom media attributes. Custom product attributes are located under “attributes” parameter.

Note: Assets linked to a single product are restricted to a limit of 300 assets per product.

Thumbnail and single media attribute linking

To link an existing asset to any of this kind of attribute, asset identifier and attribute_label are mandatory.
Caution: This action will replace existing asset in thumbnail or single media attribute if present.

Media gallery attribute linking

To link an existing asset to any of this kind of attribute, asset identifier and attribute_label are mandatory.
Attention: This action will add the asset to the media gallery attribute.

Example 1: link asset to thumbnail

POST /api/v1/products/6397116da02483ebd6dc76e0/assets

{
   "id": "5c4ed8002f0985001e233275",
   "attribute_label": "thumbnail"
}

Example 2: link asset to custom attribute

POST /api/v1/products/6397116da02483ebd6dc76e0/assets

{
   "id": "5c4ed8002f0985001e233275",
   "attribute_label": "dummy_media_gallery"
}

Parameters

Link attributes to an existing product family

\* If any of the given attributes does not exist in the product family, it will be inserted.

Body

A 200 OK status code is returned upon success.

⚠️ Note: Product Families will require more iterations so this endpoint might be deprecated at some point.

Parameters

Unlink attributes from an existing product family

\* If any of the given attributes exist in the product family, it will be removed.

Body

A 200 OK status code is returned upon success.

⚠️ Note: Product Families will require more iterations so this endpoint might be deprecated at some point.

Parameters

Plytix PIM API relies on Bearer authentication to check a user's credentials, so a token must be provided in the header of requests in order to use this API.

Credentials can be issued by any of your Plytix account administrators, under the "API" tab of the account's admin section.

Then a POST request must be made to https://auth.plytix.com/auth/api/get-token using the following format:

Upon a successful result, you can find your token in the data array. Then you must include it in the header section of every request

Authorization: Bearer {{your_token_value}}

Please note that capitalization of Bearer must be respected and there is a __space__ between your token and the literal Bearer

Request and response example.

POST /auth/api/get-token HTTP/1.1
Content-Type: application/json
{
    "api_key": "my_apy_key" , 
    "api_password":"my secret password"
}

200 OK
{
  data: [
            {  "access_token": "token data" } 
       ]
}

Parameters

Get a list of available asset filters

This endpoint lists the available search fields when filtering assets and operations that can be carried on each field.
For a description of every field returned from this endpoint, please check _Asset_ section in this guide.

This endpoint DOES NOT support the use of the "TEXT_SEARCH" operator

A complete list of operators and their meanings is available in the main section of _filters_.

__NOTE__:The most up-to-date list of attributes and operations is always returned for this endpoint.

Parameters

This endpoint lists the available search fields when filtering products and operations that can be carried on each field.
A complete list of operators and their meanings is available in the main section of _filters_.

System attributes

All products have a predefined set of system attributes shown below:

Custom attributes

User defined attributes are returned too by this endpoint, they can be easily identified as all user attribute is always
prefixed with the literal attributes..

For example, an attribute named _color_ defined as multiselect with the following values _Blue, Purple, White, Beige, and Orange_ will be returned as:

{
  "filter_type": "MultiSelectAttribute",
  "key": "attributes.color",
  "operators": [
                 "exists",
                 "!exists",
                 "in",
                 "!in"
               ],
  "options": [
                "Blue",
                "Purple",
                "White",
                "Beige",
                "Orange"
             ]
        },```

# Available properties:

| Field         | Description |
| ---           | ---  |
| `_is_variation` | True if a product is a variation |
| `_has_variations` | True if a product is a base product |

Parameters

Get a list of available relationship filters

This endpoint lists the available search fields when filtering relationships and operations that can be carried out in each field.
For a description of every field returned from this endpoint, please check the _Relationships_ section in this guide.

This endpoint DOES NOT support the use of the "TEXT_SEARCH" operator

A complete list of operators and their meanings is available in the main section of _filters_.

__NOTE__: The most up-to-date list of attributes and operations is always returned for this endpoint.

Parameters

Get all categories related to this product

Parameters

Link an existing category to this product.

Parameters

Gets a product's category by id

Parameters

Removes relationship between a product and category. Category is not deleted

Parameters

Using this verb you can change some of the properties of any group.

Allowed properties:

A 200 OK is returned upon successful request

• order: if group order is greater than the number of existing groups, group will be moved to the last position

• attribute_labels: If present, group will be modified. Please note that a request like 'attribute_labels': null will remove ALL attributes from this group

Parameters

Remove a group from the system

Parameters

Upon successful creation, a 201 CREATED status code is returned and product attribute group data can be found in response body.

Example

More examples can be found in example requests

1.- Create new group named "Dimensions"

Formatted JSON Data
{
	"name":"Dimensions",
}
 ```
Response
```json
Formatted JSON Data
{
	"attribute_labels": [
		"product_weight_kg",
		"product_length_mm",
		"product_width_mm",
		"product_height_mm",
		"packed_product_weight_kg",
		"packed_product_length_mm",
		"packed_product_width_mm",
		"packed_product_height_mm"
		],
		"order": 1,
		"name": "Dimensions",
		"id": "5d0baf02d4bf5513d19023f5"
}
 ```

Parameters

Filter product attribute groups by multiple criteria

Filter structure and format is described under the Resources section in this guide.

Restrictions

• Search requests

• Search filters MUST include all necessary columns. If an attribute is not explicitly requested it won’t be returned by the API. Available attributes can be found later in this section.

Requesting non-existing attributes will return a 422 error code.
You are allowed to sort by columns not included in the “attributes” field, however, this attribute won’t be returned

Response Format

Endpoint successful responses are wrapped in { data: [ ...] } object as in any other search endpoint.
You can read more about response format in the __Resources__ section in this guide.

Basic Example

1.- Search for all product groups and all fields (a.k.a no-filters) 100 items max.

Formatted JSON Data
{  
   "filters":[],
   "attributes":[  
      "name",
      "order",
      "attribute_labels",
   ],
   "pagination":{  
      "page_size":100,
      "page":1,
      "order":""
   }
}
 ```
Response
```json
Formatted JSON Data
{
    "data": [
        {
            "order": 0,
            "name": "Basic Information",
            "id": "5d0baf02d4bf5513d19023f3",
            "attribute_labels": [
                "gtin",
                "brand",
                "title",
                "basic_info_complete"
            ]
        },
        {
            "order": 2,
            "name": "Rich Information",
            "id": "5d0baf02d4bf5513d19023f4",
            "attribute_labels": [
                "gtin",
                "brand",
                "title",
                "new_images_gallery",
                "description",
                "feature_description",
                "hero_image",
                "additional_image_galery",
                "video_url",
                "suggested_retail_price",
                "type",
                "product_type",
                "color",
                "rich_info_complete",
                "bathroom_picture",
                "collection",
                "availability",
                "condition"
            ]
        },
        {
            "attribute_labels": [
                "product_weight_kg",
                "product_length_mm",
                "product_width_mm",
                "product_height_mm",
                "packed_product_weight_kg",
                "packed_product_length_mm",
                "packed_product_width_mm",
                "packed_product_height_mm"
            ],
            "order": 1,
            "name": "Dimensions",
            "id": "5d0baf02d4bf5513d19023f5"
        }
    ],
    "pagination": {
        "count": 3,
        "total_count": 3,
        "page": 1,
        "page_size": 100,
        "order": ""
    },

}

2.- Search for "Rich info complete" group.

Formatted JSON Data
{  
   "filters":[[{"field":"name","operator":"like","value":"RiCh InFo"}]],
   "attributes":[  
      "name",
      "order",
      "attribute_labels"
   ],
   "pagination":{  
      "page_size":25,
      "page":1,
      "order":""
   }
}

 ```
Response
```json
Formatted JSON Data
{
  "data": [
        {
            "order": 2,
            "name": "Rich Information",
            "id": "5d0baf02d4bf5513d19023f4",
            "attribute_labels": [
                "gtin",
                "brand",
                "title",
                "new_images_gallery",
                "description",
                "feature_description",
                "hero_image",
                "additional_image_galery",
                "video_url",
                "suggested_retail_price",
                "type",
                "product_type",
                "color",
                "rich_info_complete",
                "bathroom_picture",
                "collection",
                "availability",
                "condition"
            ]
        }
  ], 
  "pagination": {
    "count": 1, 
    "order": null, 
    "page": 1, 
    "page_size": 25, 
    "total_count": 3
  }
}

 ```

Parameters

Deletes an attribute. An empty response and 202 code is returned upon successful call.

You are not allowed to delete any attribute used in some E-Catalog, Channel or Pdf-Catalog and a 409 CONFLICT response code will be returned and some information on where this attribue is used.

Parameters

Retrieves a product attribute by id

Parameters

This resource allows you to modify some properties of existing attributes.

• All attributes can patch name and description fields

• DropdownAttribute and MultiselecAttributes can also patch available options. NOTE options will replace existing ones

• CompletenessAttribute can patch its "attributes".

Parameters

Create a new product attribute.

Upon successful creation, a 201 CREATED status code is returned and product attribute can be found in response body.

Example

More examples can be found in example requests

1.- Create new True/ False (Boolean) attribute named "In Stock"

Formatted JSON Data
{
	"name":"In Stock",
	"type_class":"BooleanAttribute"
}
 ```
Response
```json
Formatted JSON Data
{
  "data": [
    {
      "id": "5d0b4ea525abd700016fc037", 
      "label": "in_stock", 
      "name": "In Stock", 
      "groups": [], 
      "type_class": "BooleanAttribute"
    }
  ]
}
 ```

Parameters

Filter product attributes by multiple criteria

Filter structure and format is described under Resources section in this guide.

Restrictions

• Search requests

• Search filters MUST include all necessary columns. If an attribute is not explicitly requested it won’t be returned by the API. Available attributes can be found later in this section.

Requesting non-existing attributes will return a 422 error code.
You are allowed to sort by columns not included in “attributes” field, however this attribute won’t be returned

Response Format

Endpoint successful responses are wrapped in { data: [ ...] } object as in any other search endpoint. You can read more about response format in __Resources__ section in this guide.

All attributes share a set of common fields while some attributes also have some custom attributes, current version supports the following attributes*.

• Please DO NOT rely in any other attribute returned by endpoints as they can dissapear in future releases of the API

Basic Example

Complex examples can be found in code examples

1.- Search for all product attributes and all fields (a.k.a no-filters) 100 items max.

Formatted JSON Data
{  
   "filters":[],
   "attributes":[  
      "name",
      "label",
      "attributes",
      "groups",
      "type_class",
      "options"
   ],
   "pagination":{  
      "page_size":100,
      "page":1,
      "order":""
   }
}
 ```
Response
```json
Formatted JSON Data
{  
   "data":[
       {
	        "id": "5d00ae1aebd6f0000170c3d5", 
	        "label": "in_stock", 
	        "name": "In Stock", 
	        "type_class": "BooleanAttribute",
	        "groups": [
		        "5d00d00fc3ddd200018d92f4"
		     ] 
    	},
    	{
    		"id": "5d0384c339d49f0001391965", 
    		"name": "color", 
    		"label": "color", 
    		"groups": [], 
    		"options": [
	    		"blue",
	    		"black", 
	    		"green", 
	    		"red"
    		], 
	    	"type_class": "MultiSelectAttribute"
    	}
   ],
   "pagination":{
     "count": 2, 
     "order": "", 
     "page": 1, 
     "page_size": 100, 
     "total_count": 2
   }
}
 ```
 
 2.- Search for "Rich info complete" completeness attribute. This completeness attribute is formed by System attributes: 'sku' and 'label' and product attribute 'Additional Image Gallery'
```json
Formatted JSON Data
{  
   "filters":[[{"field":"name","operator":"like","value":"RiCh InFo"}]],
   "attributes":[  
      "name",
      "label",
      "attributes",
      "type_class",
   ],
   "pagination":{  
      "page_size":25,
      "page":1,
      "order":""
   }
}

 ```
Response
```json
Formatted JSON Data
{
  "data": [
    {
      "attributes": [
        {
          "id": null, 
          "label": "sku"
        }, 
        {
          "id": null, 
          "label": "label"
        }, 
        {
          "id": "5c582c9c9e877f04666c64ac", 
          "label": "additional_image_gallery"
        }
      ], 
      "id": "5c766b364931b805abd334a0", 
      "label": "rich_info_complete", 
      "name": "Rich Info Complete ", 
      "type_class": "CompletenessAttribute"
    }
  ], 
  "pagination": {
    "count": 1, 
    "order": null, 
    "page": 1, 
    "page_size": 25, 
    "total_count": 82
  }
}

 ```

Parameters

Create a new product family.

Upon successful creation, a 201 CREATED status code is returned and product family can be found in response body.

⚠️ Note: Product Families will require more iterations so this endpoint might be deprecated at some point.

Parameters

Edit product family name.

Current version of the API supports the following attributes:

Any other attributes will be ignored.

⚠️ Note: Product Families will require more iterations so this endpoint might be deprecated at some point.

Parameters

Retrieves a product family by id.

⚠️ Note: Product Families will require more iterations so this endpoint might be deprecated at some point.

Parameters

Remove a product family from user’s account.

A 200 OK status code is returned upon success.

⚠️ Note: Product Families will require more iterations so this endpoint might be deprecated at some point.

Parameters

Search existing product families.

Filter structure and format is described under the Resources section in this guide.

Comments:

\* Search filters MUST include all necessary columns. If an attribute is not explicitly requested it won’t be returned by the API.
Available attributes can be found later in this section.
\* Requesting non-existing attributes will return a 422 error code.
\* You are allowed to sort by columns not included in the “attributes” field, however, this attribute won’t be returned.

⚠️ Note: Product Families will require more iterations so this endpoint might be deprecated at some point.

Parameters

Add a new sub-category under an existing category

Parameters

Assign a family to a product

Parameters

Deletes a category and all its subcategories.

WARNING All subcategories will be removed too.

If you want to preserve some of the subcategories it's mandatory you move them before deleting parent category.

A 204 response is returned upon success.

If category to be deleted, or any of its subcategories, is used as root category in some E-Catalog a 409 response code will be returned. Please look at https://help.plytix.com/designing-e-catalogs for more information on E-Catalogs and filters

Parameters

Gets product attributes

This verb accepts a query parameter named __all_attributes__ which allows to specify if empty attributes should be included on response as null.

200 code is returned upon success

Params

Parameters

Modifies attributes from product, resetting the rest to its default value.

Parameters

Using this verb you can change some of the properties of any category.

Allowed properties:

Note: parent_id and sort_children are not allowed in the same request.

Moving Categories

Convert to root category (a.k.a first level categories)

You must issue a patch request to https://pim.plytix.com/api/v1/categories/product/categoryId (see examples) specifiying parent_id as empty string, i.e. {"parent_id": ""}

Move as subcategory of another category

You must issue a patch request to https://pim.plytix.com/api/v1/categories/product/categoryId (see examples) specifiying parent_id as new parent category id, i.e. {"parent_id": "new parent category here"}

Sorting Categories

Sorting Root Categories

When patching root categories (a.k.a first level categories) only reorder is allowed and must be done under the special endpoint https://pim.plytix.com/api/v1/categories/product/root, 200 status code is returned upon successful response and empty data array is returned.

Sorting Subcategories

A patch request must be issued to parent ID category including in its body a dictionary with ALL subcategories in desired order, you are not allowed to make partial orders or add new categories or this operations will return 422 error code.

{ 'sort_children': [ subcategory_ids ]

Parameters

Modifies attributes from product, leaving the rest unchanged.

Parameters

Removes a product from the PIM

__WARNING__: All variations related to this product will be removed.

This verb accepts a query parameter named __mode__ which allows to specify what to do with variations, allowed values are shown in the table below and example requests can be found in the examples.

If you want to preserve just some of the variations, it's mandatory that you unlink
them (a.k.a convert to independent products) from this product by means of the
DELETE /products/:product_id/variations/:variation_id operation.

204 code is returned upon success

Parameters

Parameters

Creates a product

There's only a mandatory parameter, _sku_ of the product. Readonly and unknown parameters will be
ignored from request data.

__Note__: This method does not allow the creation of new attributes, categories or assets.

Custom product attributes are located under “attributes” parameter. Thumbnail, assets, categories, media and media galleries
can be _linked_ to a product.

Upon successful creation, a 201 http status code will be returned, the new product
will be in the response body of the request and it resource identifier could be found
in response headers.

Thumbnail, assets and media attribute linking

You are not allowed to upload any new assets to your PIM account using this resource, thats Asset's endpoint business, but
you are allowed to _link_ existing assets into your product.
To link an existing asset to any of this kind of attribute, only asset identifier is mandatory

Media gallery

Media gallery contains a collection of medias, so in this case you need to indicate an array of _asset_ objects.
All constraints described in asset linking section apply.

Categories linking

All constrains described in asset linking section apply to categories. Only _id_ of the category is mandatory.

Example 1. Product creation

POST /api/v1/products/

{
   "sku": "blue adventure mug S023",
   "label": "Adventure mug",
   "attributes" : {
          "stock" : 123,
          "vendor_url": "http://acme.com",
          "since": "2015-03-28",
          "Media_gallery":[
                {"id":"5bfaced551e7590001486763"},
                {"id":"5bfaced551e7590001486765"}
          ],
    	    "media_single_1": {"id":"5bfaced551e7590001486764"},
      },
    "categories": [
           {
               "id": "5bfa91ab8544120001bd9078"
           }
    ]
}

201 CREATED
HEADER
Location →https://pim.plytix.com/api/v1/products/5bfad5ca5b84b100017a8f5a
BODY
{
    "data": [
        {
            "assets": [],
            "attributes": {
              "since": "2015-03-28",
              "stock" : "123",
              "vendor_url": "http://acme.com",
              "media_gallery": [
                    {
                        "filename": "1.jpeg",
                        "id": "5bfaced551e7590001486763",
                        "thumb": "https://files.plytix.com/api/v1.0/thumb/public_files/pim/assets/d1/6d/8e/5b/5b8e6dd17f7f46000c7e9629/images/d5/ce/fa/5b/5bfaced551e7590001486763/1.jpeg",
                        "url": "https://files.plytix.com/api/v1.0/file/public_files/pim/assets/d1/6d/8e/5b/5b8e6dd17f7f46000c7e9629/images/d5/ce/fa/5b/5bfaced551e7590001486763/1.jpeg"
                    },
                    {
                        "filename": "3.jpeg",
                        "id": "5bfaced551e7590001486765",
                        "thumb": "https://files.plytix.com/api/v1.0/thumb/public_files/pim/assets/d1/6d/8e/5b/5b8e6dd17f7f46000c7e9629/images/d5/ce/fa/5b/5bfaced551e7590001486765/3.jpeg",
                        "url": "https://files.plytix.com/api/v1.0/file/public_files/pim/assets/d1/6d/8e/5b/5b8e6dd17f7f46000c7e9629/images/d5/ce/fa/5b/5bfaced551e7590001486765/3.jpeg"
                    }
                ],
                "media_single_1": {
                    "filename": "2.jpeg",
                    "id": "5bfaced551e7590001486764",
                    "path": "assets/d1/6d/8e/5b/5b8e6dd17f7f46000c7e9629/images/d5/ce/fa/5b/5bfaced551e7590001486764/2.jpeg",
                    "thumb": "https://files.plytix.com/api/v1.0/thumb/public_files/pim/assets/d1/6d/8e/5b/5b8e6dd17f7f46000c7e9629/images/d5/ce/fa/5b/5bfaced551e7590001486764/2.jpeg"
                },

            },
            "categories": [
                   {
                       "id": "5bfa91ab8544120001bd9078",
                       "name" : "Mugs",
                       "path": [ "Mugs" , "Ceramic"  ]
                   }
            ],
            "id": "5bfad5ca5b84b100017a8f5a",
            "created": "2018-11-25T17:03:06.596000+00:00",
            "modified": "2018-11-25T17:03:06.628000+00:00",
            "sku": " blue adventure mug S023",
            "label": "Adventure mug",
            "status": "Draft",
            "num_variations": 0,
            "thumbnail": null,
            "assets": [ { "id":"..." }, { "id":"..." }]
        }
    ]
}

Parameters

Filter on available product categories by multiple criteria

Filter structure and format is described under Resources section in this guide

Current version of the API supports the following set of fields

Restrictions

• Search requests

• Search filters MUST include all necessary columns (except ID which is returned by default). If an attribute is not explicitly requested it won’t be returned by the API.

Available attributes can be obtained by means of the available https://pim.plytix.com/api/v1/filters/ endpoint. “key” value is what MUST be used in requests.
Requesting non-existing attributes will return a 422 error code
You are allowed to sort by columns not included in “attributes” field, however this attribute won’t be returned

• Search filters will return a 422 error code if any of the following conditions is met:

a) Field does not exist
b) Operator is not allowed for the given field (available operators and fields can be obtained using /filters/{item} endpoint)
c) Value has no meaning for the given operator. The arity of available operators can be found in API documentation

• Pagination: the number of items that can be requested (pagination.page_size) is limited to a maximum 100 items.

A 422 code will be returned from API if this limit is exceeded. If paginations is omitted 25 items of the first page will be returned.

Parameters

Filter product by multiple criteria

Filter structure and format is described under Resources section in this guide

Product search has also support to filter products based on relationship properties. Relationship filter structure and format is described later in this document.

__Please take notice of the use of attribute labels instead of attribute names in the request__ (see more examples below)

Restrictions

• Search requests

• Requests are limited to 50 attributes (plus ID and SKU which are always returned). Attributes (both system and user) and properties count in this limit. Requests having more than 50 attributes will be rejected and a 422 code will be returned from API

• __User attributes MUST be prefixed with “attributes.” (including the dot at the end) + the label of the attribute__ . So for example, if there is an attribute named “In Stock” and labeled as "in_stock" we MUST add it to the request as “attributes.in_stock”. Attribute names and labels can be obtained by

means of the filters/product endpoint

• __Relationship columns can also be requested. These MUST be prefixed with “relationships.” (including the dot at the end) + the label of the relationship__ (response is described in later in this section). Examples:

• relationships.gift_basket

• relationships.recommended_products

• Search filters MUST include all necessary columns. If an attribute is not explicitly requested it won’t be returned by the API.

Available attributes can be obtained by means of the available https://pim.plytix.com/api/v1/filters/ endpoint. “key” value is what MUST be used in requests.
Requesting non-existing attributes will return a 422 error code
You are allowed to sort by columns not included in “attributes” field however this attribute won’t be returned __User attributes MUST be prefixed with “attributes.” (including the dot at the end) + the label of the attribute__

• Search filters will return a 422 error code if any of the following conditions are met:

a) The field does not exist
b) Operator is not allowed for the given field (available operators and fields can be obtained using /filters/{item} endpoint)
c) Value has no meaning for the given operator. The arity of available operators can be found in API documentation

• Pagination: the number of items that can be requested (pagination.page_size) is limited to a maximum of 100 items. A 422 code will be returned from API if this limit is exceeded. If pagination is omitted 25 items of the first page will be returned

• Only one relationship can be selected in filters

Relationship information in responses

When relationship columns are requested, product response will include a new field named ‘relationships’ with the following structure

Relationship information

Relationship Data

~~~~
Attributes: ["categories", "label", "attributes.color", "relationships.gift_basket"]

{

 "id": "5d8200527313382d939838c4",
 "sku": "1234567890",
 "categories": [],
 "label": "Strawberry_soap",
 "attributes": {
 	"color": "red" 
 },
 "relationships": [
   {
	 "relationship_id": "5ddbf89efbe0f86e3c1574c6",
	 "label": "gift_basket",
     "related_products": [
       {
         "product_id": "5c98ef754a6c252c96793574",
         "quantity": 1
       }
     ]
   }
 ],

}

~~~~

Relationship filters

This section describes the structure and format for relationship filters. A Relationship filter is compound of several fields, some of them are mandatory while others depend on the values and options selected.

Structure

Complex filters can be built defining additional constraints on relationship quantity operator when relationship “exists” operator is selected. Please check the examples section.

Product_ids structure

Available operators:

Examples

1.- Return default page (1) with default items per page (25) using default order (no order)
Note that this query will return just ID and SKU as no _attributes_ have been provided

 {
     "filters":[
        [
            {"field":"modified","operator":"gt","value":"2018-11-01"},
            {"field":"modified","operator":"lt","value":"2018-11-30"}
        ],
        [
            {"field":"attributes.name","operator":"like","value":"unicorn"}
        ]
        ]
 }
 ```

2.- Return default page (1) with default items per page (25) using default order (no order) of product attributes SKU, Label and user attributes "In Stock" and "Volumen (liters)". **Please take notice of the the use of attribute labels instead of attribute names in the request** 
```json
 {
     "attributes":["sku", "label", "attributes.in_stock", "attributes.volume_liters"]
 }
 ```

3.- Return page 3 of products modified [ between November the 1st AND November the 30th]  OR [ contains the literal 'unicorn' ] ordered by SKU descending
returning system_attributes: id, sku, created, and user attribute "In Stock", "Product name", "Quantity" (labels: in_stock, name, qty)
```json
 {
    "filters":[
        [
            {"field":"modified","operator":"gt","value":"2018-11-01"},
            {"field":"modified","operator":"lt","value":"2018-11-30"}
        ],
        [
            {"field":"attributes.name","operator":"like","value":"unicorn"}
        ]
        ],
    "pagination":{"order":"-sku","page":3,"page_size":25},
    "attributes":["created", "attributes.in_stock", "attributes.name", "attributes.qty"]
}
 ```

# Relationship filter examples

 The following examples assume that:

 * There is a Symmetrical relationship named ‘Recommended products’.

   RP-001 is recommended with RP-002 (quantity 2) and RP-003 (quantity 3).
 So RP-002 is recommended with RP-001, and RP-003 is recommended with RP-001, however RP-002 is not related to RP-003.

 * There is an Asymmetrical relationship named “Gift basket”.

   Product GF-Basket ‘includes’ GF-Wine (2 bottles), GF-Chocolates (3 packs), GF-Emmental (1 piece)


 1. Find products where the “recommended products” relationship is defined (exists).

   ~~~~
   {
     "attributes":["relationships.recommended_products"],
     "filters":[],
     "relationship_filters":[[
       {
         "relationship_id":"5d89c6c696c8f4a322df4bbc",
         "operator":"exists",
         "product_ids":[],
       }]],
     "pagination": {
       "order":"",
       "page":1,
       "page_size":25
     }
   }
   ~~~~

 The response should include RP-001, RP-002, and RP-003

 1. Find products where “recommended products” is not defined (!exists).
   ~~~~
   {
     "attributes":["relationships.recommended_products"],
     "filters":[],
     "relationship_filters":[[
       {
         "relationship_id":"5d89c6c696c8f4a322df4bbc",
         "operator":"!exists",
         "product_ids":[]
       }]],
       "pagination":{
         "order":"",
         "page":1,
         "page_size":25
       }
   }
   ~~~~
 The response should not include RP-001, RP-002 or RP-003

 1. Find the products for which the “recommended products” relationship is defined (a.k.a exists) with the RP-002 product 
   ~~~~
   {
     "filters":[],
     "attributes":["relationships.recommended_products"],
     "relationship_filters":[[
       {
         "product_ids":[
         {
           "id":"5d89c68596c8f4a322df4bb9",
           "qty_operator":"exists",
           "value":null
         }],
         "relationship_id":"5d89c6c696c8f4a322df4bbc",
         "operator":"exists"
       }]],
     "pagination": {
       "order":null,
       "page":1,
       "page_size":25
     }
   }
   ~~~~

   Response should include RP-001
   ~~~~
   {
     "data": [
       {
         "attributes": {},
         "id": "5d89c67796c8f4a322df4bb8",
         "sku": "RP-001",
         "relationships": [
        	{
        		"relationship_id": "5d89c6c696c8f4a322df4bbc",
        		"label": "recommended_products",
        		"related_products": [
        			{
        				"product_id": "5d89c68596c8f4a322df4bb9",
        				"quantity: "2"
        			},
        			{
        				"product_id": "5d89c69496c8f4a322df4bba",
        				"quantity: "3"
        			}
        		]
        	}
         ]
       }
     ],
     "pagination": {
       "count": 1,
       "order": null,
       "page": 1,
       "page_size": 25,
       "total_count": 3
     }
   }
   ~~~~

 1. Filter the products for which the relationship with the product RP-001 is defined and whose quantity is greater than 2

   Please, note that the "value" field is an array of one element
   ~~~~
   {
       "filters": [],
       "attributes": [
           "relationships.recommended_products"
       ],
       "relationship_filters": [
           [
               {
                   "product_ids": [
                       {
                           "id": "5d89c67796c8f4a322df4bb8",
                           "qty_operator": "gt",
                           "value": [
                               2
                           ]
                       }
                   ],
                   "relationship_id": "5d89c6c696c8f4a322df4bbc",
                   "operator": "exists"
               }
           ]
       ],
       "pagination": {
           "order": null,
           "page": 1,
           "page_size": 25
       }
   }
   ~~~~

   Response should exclude RP-002, due to its quantity being 2, and include RP-003
   ~~~~
   {
     "data": [
       {
         "attributes": {},
         "id": "5d89c69496c8f4a322df4bba",
         "sku": "RP-003",
         "relationships": [
        	{
        		"relationship_id": "5d89c6c696c8f4a322df4bbc",
        		"label": "recommended_products",
        		"related_products": [
        			{
        				"product_id": "5d89c67796c8f4a322df4bb8",
        				"quantity: "3"
        			}
        		]
        	}
         ]
       }
     ],
     "pagination": {
       "count": 1,
       "order": null,
       "page": 1,
       "page_size": 25,
       "total_count": 3
     }
   }
   ~~~~

 1. Filter the products for which the relationship is defined with the product RP-001 and whose quantity is between 1 and 2

   Please, notice that the "value" field in this case, value array must include both values, i.e. [1, 2]
   ~~~~
   {
       "filters": [],
       "attributes": [
           "relationships.recommended_products"
       ],
       "relationship_filters": [
           [
               {
                   "product_ids": [
                       {
                           "id": "5d89c67796c8f4a322df4bb8",
                           "qty_operator": "bte",
                           "value": [
                               1,
                               2
                           ]
                       }
                   ],
                   "relationship_id": "5d89c6c696c8f4a322df4bbc",
                   "operator": "exists"
               }
           ]
       ],
       "pagination": {
           "order": null,
           "page": 1,
           "page_size": 25
       }
   }
   ~~~~

   Response should exclude RP-003, which has a quantity of 3, and include RP-002
   ~~~~
   {
     "data": [
       {
         "attributes": {},
         "id": "5d89c68596c8f4a322df4bb9",
         "sku": "RP-002",
         "relationships": [
        	{
        		"relationship_id": "5d89c6c696c8f4a322df4bbc",
        		"label": "recommended_products",
        		"related_products": [
        			{
        				"product_id": "5d89c68596c8f4a322df4bb9",
        				"quantity: "2"
        			}
        		]
        	}
         ]         
       }
     ],
     "pagination": {
       "order": null,
       "page": 1,
       "page_size": 25,
     }
   }
   ~~~~

 1. Find all products where ‘Gift basket’ is defined

   ~~~~
   {
       "filters": [],
       "attributes": [
           "relationships.gift_basket"
       ],
       "relationship_filters": [
           [
               {
                   "product_ids": [],
                   "relationship_id": "5d89d4fd96c8f4a322df4bc0",
                   "operator": "exists"
               }
           ]
       ],
       "pagination": {
           "order": null,
           "page": 1,
           "page_size": 25
       }
   }
   ~~~~

   The response should include 'GF-Basket' product.
   ~~~~
   {
       "data": [
           {
               "attributes": {},
               "id": "5d89d51a96c8f4a322df4bc1",
               "sku": "GF-Basket",
			   "relationships": [
        			{
        				"relationship_id": "5d89d4fd96c8f4a322df4bc0",
        				"label": "gift_basket",
        				"related_products": [
        					{
        						"product_id": "5d89d51a96c8f4a322df4bc2",
        						"quantity: "2"
        					},
							{
        						"product_id": "5d89d52f96c8f4a322df4bc3",
        						"quantity: "3"
        					},
							{
        						"product_id": "5d89d54396c8f4a322df4bc4",
        						"quantity: "1"
        					}        					
        				]
        			}
        		]               
           }
       ],
       "pagination": {
           "count": 1,
           "order": null,
           "page": 1,
           "page_size": 25,
           "total_count": 7
       }
   }
   ~~~~

Parameters

Parameters

Current version of the API supports the following attributes:

any other attributes will be ignored

Parameters

Remove a relationship from user’s account.

If the relationship is in use in an ecatalog, channel or pdf-template a 409 status code is returned along with elements where this relationship is being used.

A 204 No content is returned upon success

Parameters

Create a new relationship.

Relationship types

• Open. Unilateral relationship without any restrictions on bi-directionality. You should specify ("symmetrical" = false, open=true) parameters when creating this kind of relationship.

• One-way. Unilateral relationship that will link Product A to Product B, but not Product B to Product A. This relationship type does not support the 'open' option. You should specify ("symmetrical" = false, open=false) parameters when creating this kind of relationship.

• Two-way. This establishes a bilateral relationship that will link Product A to Product B, and also Product B to Product A equally (with same quantities). You should specify ("symmetrical" = true) parameters when creating this kind of relationship.

Note: Each product can have a maximum of 300 products related to it per relationship.

Upon successful creation, a 201 http status code will be returned.

Parameters

Assign products to an existing relationship

Behaviour

• If any of the given products already exists in the relationship, its quantity will be updated

• If any of the given products does not exist in the relationship, it will be inserted

A 201 Created status code is returned upon success

A 200 OK status code is returned if no updates in the requested relationships were performed

Request format

To assing a product to any relationship, the id of the product to be related along with its quantity must be provided.

A _product_relationship_ object is defined by:

Response format

Successful responses will be returned in "data" array and will be in the form:

A _related_product_ object is defined by:

Example:

{
    "data": [
        {
            "related_products": [
                {
                    "last_modified": "2019-09-24T17:28:07.329000+00:00",
                    "product_id": "5d6cfa8ae36dc76b0e5df8dd",
                    "quantity": 1
                },
                {
                    "last_modified": "2019-09-24T17:28:07.329000+00:00",
                    "product_id": "5d6cfa8aedd44295ac5df8de",
                    "quantity": 3
                }
            ],
            "relationship_id": "5d8a50b547397aea2a603079",
            "relationship_label": "contains",
        }
    ]
}

 ```

Parameters

Modify selected relationship attributes

Current version of the API only allows the modification of the 'quantity' attribute.
A 200 OK status code will be returned upon successful call

Request format

Response format

Successful responses will be returned in "data" array and will be in the form:

Example Request and Response:

~~~~
Request:
{

"quantity":11

}

Response
{
"data": [

{
  "last_modified": "2019-09-27T06:50:07.851682+00:00", 
  "product_id": "5d8cf911bde76bea4e2eff13", 
  "quantity": 11
}

]
}
~~~~

Parameters

Remove products from an existing relationship

A 204 No Content status code is returned upon success

Request format

Request format is the same used to assign products to a relationship except for the 'quantity' field, which is not necessary and will be ignored.

Parameters

Filter relationships by multiple criteria.

Filter structure and format is described under the Resources section in this guide, available fields can be queried using relationship filters endpoint

Parameters

Convert a product into a variation of another product.

__variation_id__ will become a variation of __product_id__

Both product and variation mustn't be variations of another product, also variation cannot have any variations.

Parameters

Removes relationship between a variation and its parent. Variation becomes an independent product. Deletion of variation from the system can be done by means of Products Endpoint. See Product deletion

Parameters

Add a variation to this product.

Parameters