Developer documentation

Dimensions

Most reporting endpoints can break their data down on a dimension. A dimension is a column you distribute the rows on, for instance by country, by campaign or by a custom field. Pass its key in the distribute_on parameter.

Not every dimension works on every endpoint. The revenue report distributes on the dimensions of the accounting rows, while the analysis API breaks the subscription measures down on its own. The "Available in" column below shows which of the two each dimension works on.

The dimensions your account supports are:

Log in, or send your API key as a bearer token, to see the dimensions set up for your account.

Members and levels

A dimension breaks the data into members. Each member has a stable id you can join on and a label in the language and terminology of the account. Some dimensions have more than one level, that is, more than one column in the key. The id_type of a level says what its ids are:

  • campaign - the Iteras ID of a campaign, the same id as returned by the campaigns endpoint. The key also carries the campaign_id configured inside Iteras.

  • product - subscriptions with the same combination of products are grouped together. Each combination has an ID. For a single product, its configured external_id is also included.

  • segment - customers belonging to the same combination of segments are grouped together. Each combination has an ID. For a single segment, its configured external_id is also included.

  • country - a two-letter ISO country code.

  • boolean - the string "true" or "false".

  • year_month - a month as YYYY-MM.

  • value - a serialized custom field value. Use the returned ID for joins and the label for display.

Treat member IDs as opaque strings; compound IDs identify the whole combination, not one product or field choice.

Custom fields as dimensions

A custom field can be a dimension. field:<field id> breaks the data down on a field of the customer, subscription, product assignment or campaign, for every field with "Distribute on" turned on in the field settings inside Iteras. The field id is the one used by the field definitions endpoint, so fill in "ID of the field" in the field settings and the dimension key survives a rename. On the analysis API, field|first_period:<field id> is a field on the campaign the subscription started on.