API documentation# 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 little thing, 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"
}
]
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 and running with that for some time until the dust has settled. Similarly, do not turn on the automatic dunning procedure until having verified that it will send reminders to the right people.
# Importing future address changes and vacations
There's a special API operation for updating customers with
future address changes and vacations, "createcustomeroverride" that takes the following parameters:
-
"override_type" - the types are:
- "change-delivery-address": change future delivery address of a customer or subscription
- "change-billing-address": change future billing address of a customer or subscription
- "pause-delivery": vacation where the delivery is paused
- "alternative-delivery": vacation with alternative delivery address
-
"begin" - when the override takes effect
-
"end" (optional) - when the override ends
-
"subscription_id" (optional) - ID of the subscription the override is related to. Required for the vacation overrides.
-
"address" (optional) - address to change to
-
"weekdays" (optional) - list of weekdays that an address change should reference
A few examples:
[
{
"id": "12345", // customer ID
"operation": "createcustomeroverride",
"subscription_id": "32142532",
"override_type": "change-delivery-address",
"begin": "2019-12-24",
"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": "createcustomeroverride",
"subscription_id": "32142532",
"override_type": "alternative-delivery",
"begin": "2019-12-24",
"end": "2019-12-31",
"address": {
"name": "Peter Jensen",
"company": "Shøp",
"address": "Vesterbro 1\n9000 Aalborg",
"country": "DK"
}
}
]