Once you have set up and published a new Dimensions, it's ready to use.

Almost all POST calls in the Loyalty API takes a dim query parameter. This is the one to use to decorate your data.

Dimensions can be specified using two equal formats:

Concatenated format

The concatenated format uses a single dim parameter to specify all Dimensions. The format is: dim = dim1 : value1 [ ; dim2 : value2 [ ; ...]].

Let's say you have three dimensions called country, channel and promotion, and you want to save a click Activity for a marketing email in the US:

POST /activities?dim=channel:email;country:US;promotion:Christmas

Split format

However an alternative to the concatenated format is to specify each dimension as a separate query parameter. This is done by prefixing each dimension with dim_.

The above post example can therefore alternatively be specified as:

POST /activities?dim_promotion=Christmas&dim_channel=email&dim_country=US

Rules and Notes

A few points worth noting:

You don't have to specify all Dimensions parameters for each call. Only pass in the ones that are relevant.
Dimensions have to be specified using the Internal Entity Id. The Dimensions name or external Id are not allowed when decorating transactions
Dimension values are case sensitive. Country 'US' is different from country 'us', so be consistent. Furthermore, Dimension values can only contain letter, digits and underscore.
Only Published Dimensions can be specified. So if you unpublish a Dimension it may call API calls to fail.
Dimensions are assigned to a transaction when the transaction is first created and then can't be modified. If for example a new Order is saved with the Dimension 'country=DE', but then gets updated by a call passing in Dimension 'country=FR', it remains being assigned to country DE.
Some Entities may have been configured with Dimension Filters. The filter may for example require that the country Dimension is specified, and that that the channel Dimension is either 'website' or 'email'. This will cause the save to fail unless the passed in dim matches the requirements.