Developer documentation

Update campaign

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

The /api/campaigns/updatecampaign/ endpoint updates an existing campaign, identified by the Iteras id (not by the self-chosen campaign_id). Only fields you include are changed, the others keep their current value. To clear a field you added yourself, set it to null.

Note When you change an existing campaign, it affects all active subscriptions on the campaign. Changes to prices or products should be done carefully, and often changes to length are better done in a new successor campaign.

Parameters

  • id string required
    The Iteras ID of the campaign to update. It is returned as id by the campaign retrieval API and by createcampaign.
  • campaign_id string
    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
    Internal campaign name shown inside Iteras, e.g. 3 months.
  • customer_facing_name string
    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

    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

    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

Change the customer facing name and the price:

POST /api/campaigns/updatecampaign/ HTTP/1.1
Content-Type: application/json{
  "id": "308",
  "customer_facing_name": "3 months",
  "lines": [
    { "text": "3 issues", "amount": 29900, "tax_rate": 0.25 }
  ]
}

Change the campaign_id of the campaign:

POST /api/campaigns/updatecampaign/ HTTP/1.1
Content-Type: application/json{
  "id": "308",
  "campaign_id": "three-issues"
}

Return value

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

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

Errors

Invalid JSON returns 400, and an unknown id returns 404.

A well-formed request with invalid values is not executed and returns 422 with the errors keyed by field.