# Retrieving campaigns

GET `https://app.iteras.dk/api/campaigns/`

The API key must allow "Retrieve campaign data".

Lists the campaigns customers can subscribe on, with their periods, prices and products.

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 IDs of the campaigns to fetch, repeating the parameter for each, e.g. `campaign_id=3months`. If left out, information for all campaigns is returned.
- `include_archived` (bool): Include archived campaigns, e.g. `include_archived=true`.
- `price_calculated_for_customer` (string): Campaign prices are calculated for the customer with this ID, which can make a difference with 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`.
- `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`, clipped to between 1 and 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-02-22`. 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](/api/docs/server/invoicelinesformat.md), 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`, `campaign_id`, `sync_with_controlling_period` and, if set, `max_controlled_subscriptions`, e.g. `[{"id": "311", "campaign_id": "employee", "sync_with_controlling_period": true, "max_controlled_subscriptions": 5}]`. 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`, `campaign_id`, `sync_with_controlling_period` and, if set, `max_controlled_subscriptions`, e.g. `[{"id": "312", "campaign_id": "digital-extra", "sync_with_controlling_period": true, "max_controlled_subscriptions": 3}]`.
- `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).

[Log in](/login/?next=/api/docs/server/campaigns.md), or send your API key as a bearer token, to see the custom campaign fields set up for your account.

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

```json
{
  "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",
          "sync_with_controlling_period": true,
          "max_controlled_subscriptions": 5
        }
      ],
      "controlled_addon_campaigns": [    // campaigns that can be added on to a subscription
        {
          "id": "312",
          "campaign_id": "digital-extra",
          "sync_with_controlling_period": true,
          "max_controlled_subscriptions": 1
        }
      ]
    }
  ]
}
```

## Errors

A `customer` or `business_entity` that does not exist returns a plain text HTTP 404 error. An `id` that isn't a number returns a plain text HTTP 400 error.