Retrieving campaigns

get https://app.iteras.dk/api/campaigns/

The /api/campaigns/ endpoint enables you to retrieve information about active campaigns. A campaign in Iteras describes what a subscription should receive in a single period, how the period is billed and if the subscription should be renewed.

Parameters

id string

Iteras ID of a specific campaign, e.g. ?id=308. Can be repeated to fetch several campaigns.
campaign_id string

Self-chosen ID of a specific campaign, e.g. ?campaign_id=3months. Can be repeated to fetch several campaigns. If left out, information for all campaigns is returned.
include_archived bool

Include archived campaigns, e.g. ?include_archived=1.
price_calculated_for_customer string

Campaign prices are calculated with the provided customer ID which sometimes make a difference, for instance if there are conditional invoice lines, e.g. ?price_calculated_for_customer=9224437.
price_calculated_for_date date

Campaign prices are calculated for a specific date, as YYYY-MM-DD, e.g. ?price_calculated_for_date=2026-10-30.
business_entity string

The external ID of the business entity to fetch campaigns for.
max_results integer Defaults to 2000

How many campaigns to retrieve at most, e.g. max_results=1000. "max_results" is currently clipped to be between 1-2000. If there are more results available, a next_url is returned which you can use to grab the next page.

Return value

The data returned is an object with an array of campaign information, possibly empty, like this {"campaigns": [{"campaign_id": 3months, ...}]}. If there are more campaigns than max_results, the response also contains a next_url you can use to fetch the next page. Each campaign object may contain the following attributes:

id string

Iteras ID of the campaign, e.g. 308. Use it to update or delete the campaign.
name string

Internal campaign name shown inside Iteras, e.g. 3 issues.
campaign_id string

Self-chosen ID of the campaign, e.g. 3months.
active bool

Whether the campaign is active, e.g. true.
customer_facing_name string

Campaign name shown to customers, e.g. Three beautiful issues.
duration_based_on string

How the period length is determined, either time or assignments, e.g. assignments.
period_assignments integer

Number of assigned products in each period, e.g. 3. Included when duration_based_on is assignments.
time string

Length of each period, either a duration such as 6m or fixed, e.g. 6m. Included when duration_based_on is time.
fixed_date date

Date the period ends, as YYYY-MM-DD, e.g. 2027-01-30. Included when time is fixed.
repeat_number_of_times integer

How many times in a row the subscription gets a period on the campaign before continuing, e.g. 2.
next_campaign string

Iteras ID of the campaign the subscription continues on, e.g. 309. Included if set.
next_campaign_id string

campaign_id of the campaign the subscription continues on, e.g. 6m. Included if set.
business_entity string

External ID of the campaign's business entity, e.g. DKbranch. Included if the business entity has an external ID.
lines array

What is invoiced for each period, in the invoice line format, e.g. [{"text": "3 issues", "amount": 24950, "tax_rate": 0.25}]. No lines means the campaign is free.
price decimal

A computed price per period, for convenience, e.g. 224.5. If you need a more precise price for a given customer or date, fill in the price_calculated_for_customer and price_calculated_for_date parameters.
currency string

Currency of the computed price, e.g. EUR.
products array

The products in the campaign, each an object with name, external_id and, for the product that counts the period, used_for_period_duration, e.g. [{"name": "Test Magazine", "external_id": "testexternal", "used_for_period_duration": true}].
pro_forma_subscription bool may change

Whether the subscription is only pro forma for accounting purposes and receives nothing, e.g. false.
receives_issues bool may change

Whether upcoming products are assigned to the subscription automatically, e.g. true.
access_content string may change

Access to previous products when integrating with digital edition platforms: "", received or all, e.g. all.
access_paywall bool may change

Whether an active subscription gets access to content protected by a paywall, e.g. true.
policy string

External ID of an overriding business policy, e.g. no_pause. Included if set.
product_image string may change

Name of the campaign's product image from the image library, e.g. cover.jpg. Included if set.
unit_price integer may change

Unit price in cents including tax, used for crediting, e.g. 150. Included if set.
controlled_group_campaigns array

Campaigns that subscriptions on this campaign can control as group recipients, each an object with id and campaign_id, e.g. [{"id": "311", "campaign_id": "employee"}]. Group structures can be nested, so a controlled campaign may itself control further campaigns.
controlled_addon_campaigns array

Campaigns that can be added on to a subscription on this campaign, each an object with id and campaign_id, e.g. [{"id": "312", "campaign_id": "digital-extra"}].
switching object

Campaigns the customer can switch to, grouped by situation, e.g. {"offered_instead_of_cancel": [{"id": "309", "campaign_id": "6m"}]}. Each key holds an array of campaign references, each an object with id and campaign_id.

allowed_from_selfservice, campaigns the customer can switch to from the self-service

offered_instead_of_cancel, campaigns offered instead of cancelling in the self-service

offered_from_invoice, campaigns offered through a link in the invoice

You can set any custom campaign field, using its field id (the field name with a colon prepended, or its external identifier).

A yes/no field (type bool) is true or false, and has no value when it isn't set. Set it with true or false, and clear it with null.

Examples

{
  "campaigns": [
    {
      "id": "308",
      "name": "3 issues",
      "campaign_id": "3i",
      "active": true,
      "customer_facing_name": "Three beautiful issues",
      "duration_based_on": "assignments",
      "period_assignments": 3,
      "price": 224.5,
      "currency": "EUR",
      "repeat_number_of_times": 2,
      "next_campaign_id": "3i",
      "business_entity": "DKbranch",  // if the business entity has an external ID
      "lines": [
        {
          "text": "3 issues",
          "amount": 24950,
          "tax_rate": 0.25
        },
        {
          "text": "Special discount",
          "percentage": -0.10
        }
      ],
      "products": [
        {
          "name": "Test Magazine",
          "external_id": "testexternal",
          "used_for_period_duration": true,
          ":Custom product field": "Example text"
        }
      ],
      "switching": {                     // campaigns this one can be switched to
        "allowed_from_selfservice": [
          {
            "id": "309",
            "campaign_id": "6m"
          }
        ],
        "offered_instead_of_cancel": [   // offered when cancelling in the selfservice
          {
            "id": "309",
            "campaign_id": "6m"
          }
        ],
        "offered_from_invoice": [        // offered by a link in the invoice
          {
            "id": "309",
            "campaign_id": "6m"
          }
        ]
      },
      ":Custom campaign field": "Example text",
    },
    {
      "id": "309",
      "name": "1/2 year",
      "campaign_id": "6m",
      "active": true,
      "customer_facing_name": "Half a year",
      "duration_based_on": "time",
      "time": "6m",
      "fixed_date": null,
      "price": 500,
      "currency": "EUR",
      "next_campaign_id": "6m",
      "lines": [
        {
          "text": "Subscription 6 months",
          "amount": 50000,
          "tax_rate": 0.0
        }
      ],
      "products": [
        {
          "name": "Test Magazine",
          "external_id": "testexternal",
          ":Custom product field": "Example text"
        }
      ],
      ":Custom campaign field": "Example text",
    },
    {
      "id": "310",
      "name": "Division",
      "campaign_id": "division",
      "active": true,
      "customer_facing_name": "Division",
      "duration_based_on": "time",
      "time": "12m",
      "price": 0,
      "currency": "EUR",
      "next_campaign_id": "division",
      "products": [],
      "controlled_group_campaigns": [    // campaigns the group can have subscriptions on
        {
          "id": "311",
          "campaign_id": "employee"
        }
      ],
      "controlled_addon_campaigns": [    // campaigns that can be added on to a subscription
        {
          "id": "312",
          "campaign_id": "digital-extra"
        }
      ]
    }
  ]
}

Errors

A customer or business_entity that does not exist returns a plain text HTTP 404 error.

# Retrieving campaigns

# Parameters

# Return value

# Examples

# Errors

Retrieving campaigns

Parameters

Return value

Examples

Errors