# Conditions format

Conditions are used for several things in Iteras: To decide whether something happens or to filter a set of objects, e.g. customers, subscriptions, etc.

The format is an array of objects, each being a condition. Each object has a condition_type that identifies the condition, plus the fields that type needs. Some conditions work on related objects and have nested sub-conditions. All the listed conditions must be met.

The following conditions match Danish customers whose email is filled in:

[
   {
     "condition_type": "customer:field",
     "field": "country",
     "operator": "in",
     "options": ["DK"]
   },
   {
     "condition_type": "customer:field",
     "field": "email",
     "operator": "filledin"
   }
]

The context the conditions are evaluated in determines which conditions are available. For instance, when filtering customers customer:field conditions are immediately available, but you need to go through a subscription:exists condition to be able to add constraints on subscriptions the customers must have.

# Customer conditions

# customer:field

Evaluation context: customer

Matches when a field on the customer satisfies the expression, see field conditions.

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

{
  "condition_type": "customer:field",
  "field": "country",
  "operator": "in",
  "options": ["DK", "SE"]
}

# customer:segment / customer:notsegment

Evaluation context: customer

Matches when the customer is in one of the segments (or not in one of the segments). Segments are defined inside Iteras as any customer matching a set of self-chosen conditions.

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

{
  "condition_type": "customer:segment",
  "segments": [
    { "external_id": "foreign" },
    { "external_id": "b2b" }
  ]
}

• segments array required
  The segments to check, e.g. [{ "external_id": "foreign" }]. Each object has an external_id matching a segment.

# customer:subscriptioncount

Evaluation context: customer

Matches when the number of active subscriptions for the customer is between from_count and to_count, both inclusive.

• from_count integer required
  The minimum number of active subscriptions.
• to_count integer
  The maximum number of active subscriptions. Omit for no upper limit.
• count_recipients boolean
  Whether to also count receivers on group subscriptions the customer controls. Defaults to false.

{
  "condition_type": "customer:subscriptioncount",
  "from_count": 2,
  "to_count": 5
}

# customer:satisfies

Evaluation context: customer

Conditions applied to the customer, e.g. [{ "condition_type": "customer:field", ... }]. Evaluation context is the customer.

{
  "condition_type": "customer:satisfies",
  "conditions": [
    {
      "condition_type": "customer:field",
      "field": "country",
      "operator": "in",
      "options": ["DK"]
    }
  ]
}

# Subscription conditions

# subscription:exists / subscription:notexists

Evaluation context: customer

Matches when the customer has, respectively, a subscription or no subscription in one of the states, where any extra conditions also apply to that subscription.

• states array
  The subscription states to match: active, awaiting, suspended or ended. Omit to match subscriptions in any state.
• conditions array
  Conditions applied to the subscription, e.g. [{ "condition_type": "subscription:product", ... }]. Evaluation context is the subscription.

{
  "condition_type": "subscription:exists",
  "states": ["active"],
  "conditions": [
    {
      "condition_type": "subscription:product",
      "products": [1, 2]
    }
  ]
}

# subscription:field

Evaluation context: subscription

Matches when a field on the subscription satisfies the expression, see field conditions.

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

# subscription:type

Evaluation context: subscription

Matches when the subscription is one of the given types.

• types array
  The subscription types to match. Each is one of standard, group, receiver, addon, proforma or not_proforma.

{
  "condition_type": "subscription:type",
  "types": ["group", "receiver"]
}

# subscription:product

Evaluation context: subscription

Matches when the subscription is on one of the given products. Products can be referenced by their external ID as well as their internal ID.

• products array required
  The products to match, as internal IDs or objects with an external_id, e.g. [1, { "external_id": "magazine" }].

{
  "condition_type": "subscription:product",
  "products": [
    { "external_id": "magazine" },
    { "external_id": "newspaper" }
  ]
}

# subscription:campaign / subscription:notcampaign

Evaluation context: subscription

Matches when the subscription is, respectively, on one of the given campaigns or not on any of them. Campaigns can be referenced by their campaign ID as well as their internal ID.

• campaigns array required
  The campaigns to match, as internal IDs or objects with a campaign_id, e.g. [12, { "campaign_id": "3months" }].

{
  "condition_type": "subscription:campaign",
  "campaigns": [
    { "campaign_id": "3months" },
    { "campaign_id": "halfyear" }
  ]
}

# subscription:campaignfield

Evaluation context: subscription

Matches when a field on the subscription's campaign satisfies the expression, see field conditions.

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

# subscription:policy

Evaluation context: subscription

Matches when the subscription is on one of the given business policies. Policies can be referenced by their external ID as well as their internal ID.

• policies array required
  The business policies to match, as internal IDs or objects with an external_id, e.g. [5, { "external_id": "schools" }].

{
  "condition_type": "subscription:policy",
  "policies": [
    { "external_id": "schools" },
    { "external_id": "libraries" }
  ]
}

# subscription:paid

Evaluation context: subscription

Matches when the subscription is paid or free.

• paid boolean
  true to match paid subscriptions, false to match free ones.

{
  "condition_type": "subscription:paid",
  "paid": true
}

# subscription:state

Evaluation context: subscription

Matches when the subscription is in one of the states.

• states array required
  The subscription states to match: active, awaiting, suspended or ended.

{
  "condition_type": "subscription:state",
  "states": ["active", "suspended"]
}

# subscription:ends / subscription:renewal / subscription:suspended

Evaluation context: subscription

subscription:ends matches when the subscription has a stop date, subscription:renewal when it has a renewal date, and subscription:suspended when it was suspended. All three take a date operator that describes the relevant date:

• operator string required
  How the date is expressed. ininterval is the default. The choices are:

  • ininterval — the date is between the two dates in date_interval, e.g. the dates 1 Jan and 31 Jan.
  • morethanago — the date is more than number unit ago, e.g. more than 3 months ago.
  • lessthanago — the date is less than number unit ago, e.g. less than 1 year ago.
  • lessthanfromnow — the date is within the next number unit, e.g. within the next 2 weeks (not supported by subscription:suspended).
  • morethanfromnow — the date is more than number unit from now, e.g. more than 6 months from now (not supported by subscription:suspended).
  • incalendarperiod — the date is in the given calendar period, described by unit and offset, e.g. this month or previous month.
• date_interval array
  The two dates, start and end, as ["YYYY-MM-DD", "YYYY-MM-DD"] for ininterval, e.g. ["2024-01-01", "2024-01-31"].
• number integer
  The amount of time for the ago and from-now operators, e.g. 3.
• unit string
  The unit of number and offset: year, month or day for the ago and from-now operators; day, month or year for incalendarperiod.
• offset integer
  Offset to apply to incalendarperiod: -1 gives the previous period, 0 the current one, 1 the next.

{
  "condition_type": "subscription:ends",
  "operator": "ininterval",
  "date_interval": ["2024-01-01", "2024-01-31"]
}

{
  "condition_type": "subscription:renewal",
  "operator": "incalendarperiod",
  "offset": 1,
  "unit": "month"
}

# Subscription period conditions

These conditions evaluate against a subscription period, not the subscription itself. A subscription period is the span of time a subscription is on a given product, so a subscription's product can change from period to period.

# subscriptionperiod:product

Evaluation context: subscription period

Matches when the subscription period is on one of the given products. Products can be referenced by their external ID as well as their internal ID.

• products array required
  The products to match, as internal IDs or objects with an external_id, e.g. [1, { "external_id": "magazine" }].

{
  "condition_type": "subscriptionperiod:product",
  "products": [
    { "external_id": "magazine" },
    { "external_id": "newspaper" }
  ]
}

# Invoice conditions

# invoice:exists / invoice:notexists

Evaluation context: customer

Matches when the customer has, respectively, an invoice or no invoice, where any extra conditions also apply to that invoice.

• conditions array
  Conditions applied to the invoice, e.g. [{ "condition_type": "invoiceline:exists", ... }]. Evaluation context is the invoice.

{
  "condition_type": "invoice:exists"
}

# invoice:field

Evaluation context: invoice

Matches when a field on the invoice satisfies the expression, see field conditions.

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

# Invoice line conditions

# invoiceline:exists

Evaluation context: invoice

Matches when the invoice has an invoice line, where any extra conditions also apply to that line.

• conditions array
  Conditions applied to the invoice line, e.g. [{ "condition_type": "invoiceline:subscriptionperiod", ... }]. Evaluation context is the invoice line.

{
  "condition_type": "invoiceline:exists"
}

# invoiceline:field

Evaluation context: invoice line

Matches when a field on the invoice line satisfies the expression, see field conditions.

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

# invoiceline:subscriptionperiod

Evaluation context: invoice line

Matches when the line is for a subscription period where the given subscription period conditions apply, e.g. subscriptionperiod:product.

• conditions array
  Conditions applied to the subscription period, e.g. [{ "condition_type": "subscriptionperiod:product", ... }]. Evaluation context is the subscription period.

{
  "condition_type": "invoiceline:subscriptionperiod",
  "conditions": [
    {
      "condition_type": "subscriptionperiod:product",
      "products": [1, 2]
    }
  ]
}

# invoiceline:productassignment

Evaluation context: invoice line

Matches when the line is for a product assignment where the given product assignment conditions apply, e.g. productassignment:field.

• conditions array
  Conditions applied to the product assignment, e.g. [{ "condition_type": "productassignment:field", ... }]. Evaluation context is the product assignment.

{
  "condition_type": "invoiceline:productassignment",
  "conditions": [
    {
      "condition_type": "productassignment:field",
      "field": "type",
      "operator": "equal",
      "value": "sample"
    }
  ]
}

# Campaign conditions

# campaign:field

Evaluation context: campaign

Matches when a field on the campaign satisfies the expression, see field conditions.

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

# campaign:campaign / campaign:notcampaign

Evaluation context: campaign

Matches when the campaign is, respectively, one of or not one of the given campaigns. Campaigns can be referenced by their campaign ID as well as their internal ID.

• campaigns array required
  The campaigns to match, as internal IDs or objects with a campaign_id, e.g. [12, { "campaign_id": "3months" }].

{
  "condition_type": "campaign:campaign",
  "campaigns": [
    { "campaign_id": "3months" },
    { "campaign_id": "halfyear" }
  ]
}

# campaign:timeduration

Evaluation context: campaign

Matches when the campaign runs for the given amount of time.

• campaign_time_duration string required
  How long the campaign runs, e.g. "3m" for three months. The unit is y, m, w or d.

{
  "condition_type": "campaign:timeduration",
  "campaign_time_duration": "3m"
}

# Product and business policy conditions

Each of these matches when a field on the object satisfies the expression, see field conditions for the operators.

# product:field

Evaluation context: product

Matches when a field on the product satisfies the expression.

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

# productassignment:field

Evaluation context: product assignment

Matches when a field on the product assignment satisfies the expression.

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

# businesspolicy:field

Evaluation context: business policy

Matches when a field on the business policy satisfies the expression.

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

# Field conditions

The *:field conditions, such as customer:field and subscription:field, describe an expression. Which operators are available depends on the field's type.

• field string required
  The ID of a field on the object the condition applies to.
• operator string required
  The operator for the expression, see below.

# filledin / notfilledin

The field is, respectively, filled in or not filled in.

A missing field, null, an empty string and an empty list are not filled in, and neither is 0 in an amount field. On a yes/no field both true and false are filled in, so use in to match one of them.

Field types: all.

# in / notin

The field is, respectively, one of or not one of the given values.

• options array required
  The allowed values, e.g. ["DK", "SE"].

Field types: choice, multiple choice, boolean.

For a yes/no (boolean) field the values are true and false.

{
  "condition_type": "customer:field",
  "field": "country",
  "operator": "in",
  "options": ["DK", "SE"]
}

# equal / notequal

The field is, respectively, the same or not the same as the given value.

• value string required
  The value to compare against, e.g. "København".

Field types: text, email, phone number, VAT number, e-invoice recipient, number, monetary.

{
  "condition_type": "customer:field",
  "field": "group",
  "operator": "equal",
  "value": "B2B"
}

# contains / notcontains

The field does, respectively, contain or not contain the given text.

• text string required
  The text to look for, e.g. "A/S".

Field types: text, email, phone number, VAT number, e-invoice recipient.

{
  "condition_type": "customer:field",
  "field": "company",
  "operator": "contains",
  "text": "A/S"
}

# oneof / notoneof

The field is, respectively, one of or not one of the given values.

• values array required
  The allowed values, e.g. ["personal", "business"].

Field types: text, email, VAT number, number.

{
  "condition_type": "customer:field",
  "field": "customer_type",
  "operator": "oneof",
  "values": ["personal", "business"]
}

# lessthan / greaterthan / lessthanequal / greaterthanequal

The field is less than, greater than, less than or equal to, or greater than or equal to the given value.

• value number required
  The value to compare against, e.g. 70. Monetary values should be written in cents, e.g. 9095 for 90.95.

Field types: number, monetary.

{
  "condition_type": "customer:field",
  "field": "price",
  "operator": "greaterthanequal",
  "value": 99.95
}

# lessthanago / morethanago

The field is a date less than or more than the given amount of time ago.

• number integer required
  How long ago, e.g. 3.
• unit string required
  The unit of number: year, month or day.

Field types: date, date-time.

{
  "condition_type": "customer:field",
  "field": "start_date",
  "operator": "morethanago",
  "number": 3,
  "unit": "month"
}

# ininterval

The field is a date between the given two dates.

• date_interval array required
  Two dates, the start and the end, as YYYY-MM-DD, e.g. ["2024-01-01", "2024-01-31"].

Field types: date, date-time.

{
  "condition_type": "customer:field",
  "field": "start_date",
  "operator": "ininterval",
  "date_interval": ["2024-01-01", "2024-01-31"]
}

# incalendarperiod

The field is a date in the given calendar period.

• offset integer required
  -1 for the last period, 0 for the current one, 1 for the next.
• unit string required
  day, week, month or year.

Field types: date, date-time.

{
  "condition_type": "customer:field",
  "field": "start_date",
  "operator": "incalendarperiod",
  "offset": -1,
  "unit": "month"
}

# match / notmatch

The field is a postcode in, respectively, one of or none of the given postcodes or intervals.

• postcode array required
  Postcodes or intervals, e.g. ["2412", "4000-4999"]. A single postcode such as 2412 or an interval such as 4000-4999.

Field types: postcode.

{
  "condition_type": "customer:field",
  "field": "postcode",
  "operator": "match",
  "postcode": ["2412", "4000-4999"]
}