saveMatrixDimension

Create a matrix dimension, or add values to an existing dimension.

A matrix dimension is necessary for setting up matrix products. Typical matrix dimensions are, for example, "Size" (in which the values might be 2, 4, 6, 8 — or S, M, L, XL) and "Color" (which may contain Blue, Red, Black, Green etc).

Different matrix products can share the same dimensions, and a matrix product does not need to have variations corresponding to each value in the dimension. For example, it is sufficient to have just one dimension for all letter sizes, one for all numeric sizes and one for all kinds of colors.

Matrix products and their variations can be created with API call getProducts.

This API call is the best choice if you want to create a brand new dimension with a specific set of values. However, if a dimension already exists and you want to modify its list of values, see the following API calls instead:

• addItemToMatrixDimension to add a new value;
• editItemInMatrixDimension to edit a value's name or code;
• removeItemsFromMatrixDimension to remove a value.

API call "saveMatrixDimension" can be used to update the list of values, too, but it is recommended to not rely on that behavior. If you specify an existing dimension's ID and a list of values, API tries to look up existing values by name (the lookup is case-insensitive). If a match is found, the code of the found value is updated; the name is not. If no match is found, a new value will be inserted.

Hence, if you have an existing dimension "Color", with values "GREEN" and "RED", and call saveMatrixDimension with the following parameters:

dimensionID = ...
valueName1 = "Green"
valueCode1 = "123"
valueName2 = "Blue"
valueCode2 = "124"

the result will be as follows:

• The code of color "GREEN" will be updated to "123". The name stays unchanged.
• A new color, "Blue", with code "124", will be added.

Considering that this API call does not report which values were matched to existing ones and which ones were added as new, it is more reliable to use addItemToMatrixDimension and editItemInMatrixDimension instead.

Input parameters

Parameter name	Description	Possible value	Required
dimensionID	Dimension ID. If this parameter is present the specified matrix dimension will be updated.	integer
name	Dimension name (eg. "Color" or "Size").	string
*****	Dimension values (pairs of names and codes) to be added and/or updated. Both name and code are required. The "#" symbol indicates the number of the pair; first pair should have names "valueName1" and "valueCode1", the second pair "valueName2" and "valueCode2", etc.
valueName#		string
valueCode#		string

Response

Field name	Type	Description
dimensionID	integer	ID of the created or updated matrix dimension.