Developer documentation

Create campaign

post https://app.iteras.dk/api/campaigns/createcampaign/

The /api/campaigns/createcampaign/ endpoint creates a new campaign. 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.

Plans are built out of campaigns. For instance, you can build a intro offer followed by the permanent plan by having a cheaper intro campaign followed by the permanent campaign. The intro campaign has its next campaign set to the permanent campaign, and the permanent campaign has its next campaign set to itself.

Parameters

  • campaign_id string required
    Self-chosen ID for the campaign, e.g. 3months. Must be unique in the account and must not collide with a product's external ID.
  • name string required
    Internal campaign name shown inside Iteras, e.g. 3 months.
  • customer_facing_name string required
    Campaign name shown to customers, e.g. 3 months.
  • business_entity string
    External ID of the business entity the campaign belongs to, e.g. DKbranch. Can be left out if the account has only one business entity.
  • products array required

    The products in the campaign, each an object identifying the product by its external_id or, if it has none, its name, e.g. [{"external_id": "example_product"}].

    When the duration of the campaign is based on counting assignments, one of the objects needs to have used_for_period_duration filled in, e.g. [{"external_id": "example_product", "used_for_period_duration": true}].

    At least one product is required unless pro_forma_subscription is true.

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

  • duration_based_on string required

    How the period length is determined. Either time for calendar time or assignments for counting assignments of products.

    If "time" is given, the time parameter must be filled in.

    If "assignments" is given, the period_assignments parameter must be filled in.

  • time string

    Length of each period in calendar time. Either a duration such as 6m for 6 months, or fixed to end on date given in the fixed_date parameter. Required when duration_based_on is time.

    Durations can be written as:

    • Nd, e.g. 3d for 3 days
    • Nw, e.g. 2w for 2 weeks
    • Nm, e.g. 6m for 6 calendar months (calculated precisely, so not the same as 6×30 days)
    • Ny, e.g. 1y for 1 calendar year (handles leap years)
  • period_assignments integer
    Number of assigned products in each period, e.g. set it to 3, and the period ends when 3 products have been assigned to the period. Required when duration_based_on is assignments.
  • fixed_date date
    Date the period ends, as YYYY-MM-DD, e.g. 2027-01-21. Required when time is fixed.
  • next_campaign_id string
    campaign_id of the campaign the subscription continues on, e.g. 3months. For introduction campaigns, this will usually be the permanent campaign. For permanent recurring campaigns, this will usually be the campaign's own campaign_id.
  • repeat_number_of_times integer Defaults to 1
    How many times in a row the subscription gets a period on the campaign before continuing, e.g. 3.
  • policy string
    External ID of a business policy to optionally override the business entity's settings with, e.g. no_pause.
  • active bool Defaults to true
    Whether the campaign is active. Once a campaign has been used, you cannot delete it, but you can make it inactive.
  • lines array
    What to invoice for each period, e.g. [{"text": "3 issues", "amount": 24950, "tax_rate": 0.25, "extra_info": ["period"]}]. See invoice line format. No lines means the campaign is free.
  • controlled_group_campaigns array
    Any recipient campaigns that can be used for recipient subscriptions for a subscription on this campaign. An array of objects with campaign_id, e.g. [{"campaign_id": "employee"}].
  • controlled_addon_campaigns array
    Any add-on campaigns that can be used for add-on subscriptions for a subscription on this campaign. An array of objects with campaign_id, e.g. [{"campaign_id": "digital-extra"}].
  • switching object

    Campaigns the customer can switch to, grouped by situation. Each key holds an array of campaign references, each an object with campaign_id, e.g. {"allowed_from_selfservice": {"campaign_id": "3months"}}.

    • 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
  • pro_forma_subscription bool Defaults to false may change
    Whether the subscription is only pro forma for accounting purposes and receives nothing.
  • product_image string may change
    Name of a image from the image library in Iteras to show as the campaign's product image, e.g. cover.jpg.
  • access_paywall bool Defaults to true may change
    Whether an active subscription gets access to content protected by a paywall.
  • access_content string Defaults to all may change

    Specifies the access to previous products when integrating with digital edition platforms. One of:

    • "", no products
    • received, assigned products
    • all, all products while active plus assigned products
  • unit_price integer may change
    In case of customer complaints that warrant crediting, you can specify the unit price in cents including tax, e.g. 150 for €1,50.
  • receives_issues bool Defaults to true may change
    For subscriptions on where products are periodically assigned, e.g. magazines, you toggle whether upcoming products are assigned to the subscription automatically. If false, products are not assigned.

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

Log in, 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 

POST /api/campaigns/createcampaign/ HTTP/1.1
Content-Type: application/json{
  "campaign_id": "3months",
  "name": "3 months",
  "customer_facing_name": "3 months",
  "business_entity": "DKbranch",
  "duration_based_on": "assignments",
  "period_assignments": 3,
  "products": [
    { "external_id": "example_product", "used_for_period_duration": true }
  ],
  "lines": [
    { "text": "3 issues", "amount": 24950, "tax_rate": 0.25 }
  ]
}

Return value

On success the endpoint returns the Iteras ID and the campaign ID of the created campaign:

{ "created": true, "id": "308", "campaign_id": "3months" }

Errors

Invalid JSON returns 400.

A well-formed request with invalid values is not executed and returns 422 with the errors keyed by field, for instance an already-used campaign_id:

{ "created": false, "errors": { "campaign_id": ["A campaign with this ID already exists."] } }

This also covers needing to specify business_entity when the account has several:

{ "created": false, "errors": { "business_entity": ["Must specify \"business_entity\"."] } }