Migrating data to Iteras

This section covers how to migrate customers and subscriptions from another system.

Before you start, you need to analyze your product offering and figure out how to map that to products and campaigns inside Iteras (we can help there). It is usually possible to simplify the existing setup considerably with the powerful tools provided by Iteras.

Once everything is configured, you can do a migration by sending the appropriate operations. Relevant operations for migrating existing customers are createcustomer and createsubscription.

For customers, you can transfer their existing ID as long as it is numerical. New customers will start from the highest ID in the database. Remember to import the original creation date so you know when they started.

For subscriptions, you need to think about how to transfer their current progress correctly. Each subscription is generally trodding along somewhere with a certain amount of duration left, of which a certain amount has been invoiced and paid. You need to transfer this to a new period inside Iteras. Generally, you should set this period to start immediately and override the remaining duration, but you can also backdate the beginning by setting period_begin. In any case, you end up with:

Duration: If the new period is full length, great, otherwise set remaining_assignments for assignment-counting campaigns or end for time-based campaigns.

Invoice status: Do you need Iteras to invoice the first period or not? If it has been invoiced already, perhaps even paid, set invoicing to "none". Otherwise, Iteras will invoice the period in full.

If you changed the duration, you can also get Iteras to invoice propertionally to the duration, e.g. a period of 1/3 of the normal duration will result in an invoice with 1/3 of the price. You do this by setting invoicing to "adjusted_begin" if you moved the beginning of the period or "adjusted_end" if you moved the end (there can be small differences in the date calculations, that's why Iteras distinguishes).

Renewed: This is a detail, but if the first period you create isn't actually the first period of the subscription (because you don't want to import all previous periods), set renewed to true so that Iteras knows that the period is the result of a renewal.

Historical periods: These can all be provided in periods. Make sure there's no overlap and that begin <= end and remember to turn off invoicing, unless they really haven't been invoiced.

Previous invoicing status: If you import periods that were invoiced in the other system and are still ongoing, you may want to tell Iteras how much was invoiced and paid previously, so that if you stop a subscription, the remainder can be credited and possibly refunded. You do this by filling in the status in external_invoicing. This is an extra complexity, so only do it for periods where you really need it. If you don't have too many of them, you could also keep track of it yourself, doing the credit in the previous system.

{
  "periods": [{
    "campaign": "3M",
    "invoicing": "none",
    "external_invoicing": {
      "invoiced": 10000,  // 100.00 DKK
      "credited": -5000,  // -50.00 DKK
      "paid": 0,
      "refunded": 0,
      "currency": "DKK",
      "tax_rate": 0.25,  // 25%
    },
    // ...
  }]
}

Extra funds: If there are extra funds registered in the other system for a customer, transfer them to Iteras with a createpayment operation on that customer with the method internal. This means that the funds are accounted for twice (in the old system and in Iteras), so if you have no other means of keeping track of that, you can register a negative payment with the specific method external in Iteras, like this (but again, this is an extra complication so only do if it necessary):

[
  {
    "operation": "createpayment",
    "id": "12345",                   // customer ID
    "amount": -10500,                // -105.00 DKK
    "currency": "DKK",
    "method": "external"
  },
  {
    "operation": "createpayment",
    "id": "12345",                   // customer ID
    "amount": 10500,                 // 105.00 DKK
    "currency": "DKK",
    "method": "internal"
  }
]

Old debt: If a customer owes money in the other system and you want Iteras to collect it from now on, you can register the debt with an invoice operation with send set to false, giving it due date and a status as if it had already been sent, so the dunning process in Iteras will send reminders and late fees for it just like any other unpaid invoice. Here's an example:

[
  {
    "operation": "invoice",
    "id": "12345",                   // customer ID
    "lines": [{
      "text": "Outstanding amount from Jan-Feb",
      "amount": 56095,               // 560.95 DKK
      "currency": "DKK",
      "tax_rate": 0.25
    }],
    "business_entity": "DKbranch",
    "due": "2026-11-09",
    "send": false,
    "note": "Debt from old system"
  }
]

Be careful with this, because Iteras has no way of knowing that the debt already exists elsewhere, so you need to make sure you don't count it twice in your bookkeeping. It is generally better to leave the debt in the old system and let it finish its dunning process, if that is at all possible.

Future address changes and vacations: These are imported with the createoverride operation. Vacations use the override types pause-delivery and alternative-delivery. A pause-delivery vacation pauses the delivery for the period, while alternative-delivery keeps the delivery going but redirects it to the address given in the override. For example:

[
  {
    "id": "12345",                   // customer ID
    "operation": "createoverride",
    "subscription_id": "32142532",
    "override_type": "change-delivery-address",
    "begin": "2025-10-09",
    "address": {
      "name": "Peter Jensen",
      "company": "Shøp",
      "address": "Vesterbro 1\n9000 Aalborg",
      "country": "DK"
    },
    "weekdays": [4, 5]  // Thursday and Friday
  },
  {
    "id": "12345",                   // customer ID
    "operation": "createoverride",
    "subscription_id": "32142532",
    "override_type": "alternative-delivery",
    "begin": "2025-10-09",
    "end": "2025-10-16",
    "address": {
      "name": "Peter Jensen",
      "company": "Shøp",
      "address": "Vesterbro 1\n9000 Aalborg",
      "country": "DK"
    }
  }
]

We have a test setup that can be used to experiment and verify the migration before going live.

Before doing the migration on live, we recommend activating manual verification of invoicing until the dust has settled. Similarly, keep the automatic dunning procedure turned off until you have manually verified that it will send reminders to the right people.

# Migrating data to Iteras

Migrating data to Iteras