Developer documentation

Retrieving customers

get https://app.iteras.dk/api/customers/

This endpoint is the entry point for retrieving information about one or more customers. Besides the fields directly on the customer, it can return subscriptions, assigned products, invoices, payments, temporary overrides, complaints and various computed values. Pick exactly what you want with the fields parameter.

Basic usage:

GET /api/customers/?id=12345&fields=data{
  "customers": [
    {
      "id": "12345",
      "data": {
        "name": "Test Person",
        "email": "someone@example.com"
      }
    }
  ]
}

Note that Iteras internally maintains more processing information about the customers and subscriptions than documented below - subscription management can be relatively complex. If you need more than what's currently available, please ask us.

Parameters

All parameters are optional.

  • id string
    A comma-separated list of customer IDs, e.g. ?id=12345,42312. If left out, information on all customers is returned.
  • max_results integer Defaults to 10000
    How many customers to retrieve at most, e.g. max_results=1000 (example). If there are more results available, a next_url is returned which you can use to grab the next page. "max_results" is currently clipped to be between 1-10000.
  • fields string Defaults to data,active_subscriptions
    A comma-separated list of fields to return in the JSON, e.g. ?fields=data,subscriptions, see below for the list.
  • filter array

    A list of conditions to filter the returned customers by, e.g. ?filter=[{ "condition_type": "customer:field", "field": ":Custom field", "operator": "filledin" }]. See conditions. The evaluation context is a customer, so subscription conditions go in a subscription:exists condition.

    Note that this does not constrain the subscriptions returned with fields=subscriptions, use filter_subscriptions for that.

  • filter_from date
    Filter the various extra entries returned for a customer, omitting data older than this date, e.g. ?filter_from=2026-07-30 - you can also specify a relative date with -3m for "3 months ago". If this filter is used when fetching invoices, payments or history entries for customers, only invoices, payments or history entries created after the date is returned.
  • filter_subscriptions array with fields=subscriptions
    A list of conditions that narrow which subscriptions are returned on each customer, e.g. [{ "condition_type": "subscription:state", "states": ["active"] }] to return only active subscriptions. If you don't filter the subscriptions, all subscriptions are returned by default (subscription constraints in the filter parameter only constrain which customers are returned). See conditions - the evaluation context is a subscription.
  • extrafield string
    Can be repeated to get additional computed fields, e.g. ?extrafield=delivered_to:formatted&extrafield=delivered_to:address:postcode.
  • iframe bool
    Set if returned URLs are intended to go in an iframe, e.g. iframe=1.
  • preauthseconds integer
    If set, URLs that go to the self-service get a pre-auth token valid for this many seconds so that the customer does not have to login to view that page, e.g. preauthseconds=3600 makes the URLs valid for an hour.
  • estimated_invoicings_until date
    Extends the simulation in estimated_invoicings until this date, e.g. ?estimated_invoicings_until=2027-01-30 (max is currently 2 years in the future) - you can also specify a relative date with +3m for "3 months from now".

Some parameters, e.g. filter and extrafield, contain special characters - remember to URL encode them.

Available fields

  • data
    All fields directly on the customer, such as name and email address.
  • active_subscriptions
    Summary of currently active subscriptions.
  • subscriptions
    All subscriptions with data on each subscription and also information about periods, begin/end dates and products received (example).
  • subscriptions.current_period
    Include current_period which contains the currently active period, the value is null if there is no active period, e.g. a stopped subscription or a subscription starting in the future.
  • subscriptions.begin
    Include subscription_begin timestamp for each subscription.
  • subscriptions.cancelled
    Include cancelled bool on each subscription, cancelled is true if a request has been made to stop the subscription.
  • subscriptions.stop_requested
    Include stop_requested timestamp on each subscription with the time a request was made to stop the subscription, if any.
  • subscriptions.end
    Include subscription_end timestamp on each subscription, if any can be deduced and it is to stop or has stopped.
  • subscriptions.invoice_lines_calculated_for_current_campaign
    Include list of invoice lines that would be invoiced on the current campaign for a full period on the subscription (the format is the same as for invoices, but with an additional campaign_id of the current campaign).
  • subscriptions.price
    Include the price field on each subscription, if filled in (this can only be done if dynamic pricing is enabled on the current campaign).
  • subscriptions.payment_agreement
    Include a payment_agreement on each subscription, if set.
  • subscriptions.allowed_complaints
    Include an allowed_complaint_dates list and an allowed_complaint_reason_codes list on each subscription, if set.
  • subscriptions.policy
    Include policy id and external_id on each subscription if any.
  • subscriptions.invoiced_by
    Include invoiced_by description on each subscription if any.
  • products
    Products that are assigned to the customer (example).
  • invoices
    Invoices, reminders and credit notes for the customer (example).
  • invoices.download_url
    Include a download_url on each invoice.
  • invoices.payment_url
    Include a payment_url on invoices that can be paid.
  • invoices.lines
    Include lines on each invoice with information on what is invoiced.
  • payments
    Payments made by the customer (example).
  • balance
    A list of the customer balance amount (paid - invoiced) for each business entity.
  • overrides
    Overrides for the customer, e.g. vacations or future changes (example).
  • complaints
    Distribution complaints by the customer (example).
  • segments
    Segments the customer is part of (example).
  • estimated_invoicings
    Simulate future processing of the subscriptions for the customer and estimate the invoice lines that would result in (example).
  • history
    Human readable log of history related to the customer (this should not be used for analytics, instead retrieve events directly).
  • password with data
    Adds the hashed customer password to the data returned.
  • password_url with data
    For customers without a password, adds a URL where the customer can set their password.
  • preauth_token with data
    Adds a pre-auth token to each customer, making it possible to automatically log them into embedded Iteras components.

Return value

The response is an object with a customers array, possibly empty. When a query finds more customers than fit in the page, the object also has a next_url you call to get the next page — see pagination.

  • customers array

    One object per customer, in order of customer number, e.g. [{ "id": "41325", "data": { ... } }, { "id": "41326", ... }]

    The customer attributes included depend on what you request, but there's always an id attribute:

    • id string
      The customer number, e.g. "41325".
  • next_url string
    URL of the next page of results, e.g. "/api/customers/?max_results=10000&fields=data". Present only when there are more results.

Note that if you have a lot of customers and need to get their data synchronized to another system, you should not use this API endpoint only. Instead check our guide on synchronizing data.

Data

Data contains the basic fields of the customer, including any custom fields defined, and may also contain computed fields if you request them. Fields not filled in on the customer are generally excluded.

  • created datetime
    When the customer was created, as YYYY-MM-DDTHH:MM:SS, e.g. 2026-07-30T23:57:57.
  • email string
    The email address, e.g. "anna@example.com".
  • name string
    The name, e.g. "Anna Hansen".
  • company string
    The company, e.g. "Hansen & Co.".
  • address string deprecated
    The address with name and country, e.g. "Anna Hansen\nRådhuspladsen 2\n1550 København V\nDenmark". Deprecated, use formatted_address.
  • formatted_address string
    The address with name and country, e.g. "Anna Hansen\nRådhuspladsen 2\n1550 København V\nDenmark".
  • location string
    The address without name or country, e.g. "Rådhuspladsen 2, 3. th.\n1550 København V".
  • country string deprecated
    The country, e.g. "Denmark". Deprecated, use country_name and country_code.
  • country_name string
    The country name, e.g. "Denmark".
  • country_code string
    The country code, e.g. "DK".
  • billing_email string
    A separate billing email, if set, e.g. "accounts@example.com".
  • billing_address string deprecated
    The billing address with name and country, e.g. "Hansen & Co.\nRådhuspladsen 2\n1550 København V\nDenmark". Deprecated, use billing_formatted_address.
  • billing_formatted_address string
    The billing address with name and country, e.g. "Hansen & Co.\nRådhuspladsen 2\n1550 København V\nDenmark".
  • billing_location string
    The billing address without name or country, e.g. "Rådhuspladsen 2\n1550 København V".
  • billing_country string deprecated
    The billing country, e.g. "Denmark". Deprecated, use billing_country_name and billing_country_code.
  • billing_country_name string
    The billing country name, e.g. "Denmark".
  • billing_country_code string
    The billing country code, e.g. "DK".
  • password string with fields=password
    The hashed customer password.
  • password_url string with fields=password_url
    For customers without a password, a URL where the customer can set their password.
  • preauth_token string with fields=preauth_token
    A pre-auth token that can log the customer into embedded Iteras components.

You can set any custom customer 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 customer 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.

A date and time field (type datetime) can be set up to follow other fields, so it is set to the time one of them changes. If the same update changes the date and time field itself, that value is kept.

GET /api/customers/?id=12345,12346&fields=data{
  "customers": [
    {
      "id": "12345",

      "data": {
        "name": "Anna Hansen",
        "email": "anna@example.com",
        "formatted_address": "Anna Hansen\nRådhuspladsen 2, 3. th.\n1550 København V\nDenmark",
        "location": "Rådhuspladsen 2, 3. th.\n1550 København V",
        "country_name": "Denmark",
        "country_code": "DK",
        "created": "2026-07-30T23:57:57",
        ":Custom field": "Example text",
        ":Custom date field": "2026-09-30"
      }
    },

    // ...
  ]
}

Active subscriptions

  • active_subscriptions array with fields=active_subscriptions

    Active subscriptions is a short-hand if you just need to know a few basic facts about the subscriptions:

    • period_id string
      The ID of the active period, e.g. "8723465".
    • subscription_id string
      The ID of the subscription, e.g. "7612471".
    • campaign string
      The Iteras ID of the campaign.
    • campaign_id string
      The campaign's self-chosen ID, e.g. "3i".
    • campaign_name string
      The internal campaign name, e.g. "3 issues".
    • campaign_customer_facing_name string
      The campaign name shown to customers, e.g. "Beautiful 3 issues".
    • data object
      The subscription's data.
    • subscribed_to array
      Products the subscription is subscribed to.
    • quantity integer
      The quantity, if not one, e.g. 2.
    • group string deprecated
      recipient, admin or admin+recipient, for a group subscription.
    • group_customer_id string
      The customer number of the group owner, for a recipient subscription, e.g. "123456".
    • group_subscription_id string
      The ID of the group subscription, for a recipient subscription, e.g. "654321".
    • addon_base_subscription_id string
      The ID of the base subscription, for an add-on subscription, e.g. "654322". 
GET /api/customers/?id=12345,12346&fields=active_subscriptions{
  "customers": [
    {
      "id": "12345",

      "active_subscriptions": [
        {
          "period_id": "8723465",
          "subscription_id": "7612471",
          "campaign_name": "3 issues",
          "campaign_customer_facing_name": "Beautiful 3 issues",
          "campaign_id": "3i",
          "group_customer_id": "123456",     // filled in if it's a recipient subscription
          "group_subscription_id": "654321"  // points to the group subscription
        },
        {
          "period_id": "8723465",
          "subscription_id": "7612472",
          "campaign_name": "6 months",
          "campaign_customer_facing_name": "6 months of bliss",
          "campaign_id": "6m",
          "addon_base_subscription_id": "7612471"  // filled in with base subscription if this is an add-on subscription to the base
        }
      ]
    },

    // ...
  ]
}

Subscriptions

  • subscriptions array with fields=subscriptions

    All subscriptions with data on each subscription and information about periods, begin/end dates and products received.

    • id string
      The ID of the subscription, e.g. "7612471".
    • created datetime
      When the subscription was created, as YYYY-MM-DDTHH:MM:SS, e.g. 2026-08-30T23:57:57.
    • data object
      The subscription's data, including the custom subscription fields.

    You can set any custom subscription 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 subscription 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.

    • state string
      The subscription state: awaiting, active, suspended, ended or stopped.
    • business_entity string
      The external ID of the business entity, if it has one, e.g. "DKbusiness".
    • periods array

      One object per period, in order of begin, earliest first.

      • id string
        The ID of the period, e.g. "835270".
      • campaign string
        The Iteras ID of the campaign, e.g. "12345".
      • campaign_id string
        The campaign's self-chosen ID, e.g. "3i".
      • campaign_name string
        The internal campaign name, e.g. "3 issues".
      • campaign_customer_facing_name string
        The campaign name shown to customers, e.g. "Beautiful 3 issues".
      • begin datetime
        When the period begins, as YYYY-MM-DDTHH:MM:SS, e.g. 2026-08-30T23:57:57.
      • end datetime
        When the period ends, as YYYY-MM-DDTHH:MM:SS, null if it is ongoing.
      • current bool
        Whether the period is currently active, e.g. true.
      • subscribed_to array
        Products the subscription is subscribed to in this period.
      • products array
        Products assigned to the period, e.g. issues contained in it.
      • group_customer_id string
        The customer number of the group owner, for a recipient subscription.
      • group_subscription_id string
        The ID of the group subscription, for a recipient subscription.
      • addon_base_subscription_id string
        The ID of the base subscription, for an add-on subscription.
      • quantity integer
        The quantity, if not one, e.g. 2.
    • current_period object with fields=subscriptions.current_period
      The currently active period, in the same format as a period in periods. null when there is no active period.
    • subscription_begin datetime with fields=subscriptions.begin
      When the subscription began, as YYYY-MM-DDTHH:MM:SS, e.g. 2026-08-30T23:57:57.
    • cancelled bool with fields=subscriptions.cancelled
      Whether a stop has been requested.
    • stop_requested datetime with fields=subscriptions.stop_requested
      When a stop was requested, if any, as YYYY-MM-DDTHH:MM:SS, e.g. 2026-09-30T23:57:57.
    • subscription_end datetime with fields=subscriptions.end
      When the subscription ends or has ended, if it can be deduced, as YYYY-MM-DDTHH:MM:SS, e.g. 2026-12-30T23:57:57.
    • invoice_lines_calculated_for_current_campaign array with fields=subscriptions.invoice_lines_calculated_for_current_campaign
      The invoice lines a full period on the current campaign would be invoiced, in the same format as lines on invoices, with an additional campaign_id, e.g. [{ "text": "3 months", "amount": 24950, "tax_rate": 0.25, "campaign_id": "3m" }].
    • price decimal with fields=subscriptions.price
      The price of the subscription, if filled in, e.g. 99.95.
    • currency string with fields=subscriptions.price
      The currency of the price, e.g. "EUR".
    • payment_agreement object with fields=subscriptions.payment_agreement

      The payment agreement of the subscription.

      • id string
        The ID of the payment agreement.
      • text string
        A human-readable description of the payment agreement.
      • created datetime
        When the payment agreement was created, as YYYY-MM-DDTHH:MM:SS.
    • policy object with fields=subscriptions.policy

      An overriding business policy, if set on the subscription.

      • id string
        The ID of the policy.
      • external_id string
        The external ID of the policy.
    • invoiced_by string with fields=subscriptions.invoiced_by
      How the subscription is invoiced, e.g. "E-mail".
    • allowed_complaint_dates array with fields=subscriptions.allowed_complaints
      The dates a complaint can be filed, if any, e.g. ["2026-10-27", "2026-10-29"].
    • allowed_complaint_reason_codes array with fields=subscriptions.allowed_complaints
      The reason codes that can be used for a complaint, if any, e.g. ["20", "25"].
    • products array
      Products assigned directly to the subscription, if any, e.g. [{"id": "9976483", "name": "Name"}].
    • group string deprecated
      recipient, admin or admin+recipient, for a group subscription.
    • group_customer_id string
      The customer number of the group owner, for a recipient subscription, e.g. "123456".
    • group_subscription_id string
      The ID of the group subscription, for a recipient subscription, e.g. "654321".
    • addon_base_subscription_id string
      The ID of the base subscription, for an add-on subscription, e.g. "654322".
    • quantity integer
      The quantity, if not one, e.g. 2.

Here's an example where subscriptions are requested:

GET /api/customers/?id=12345,12346&fields=subscriptions,subscriptions.price,subscriptions.payment_agreement,subscriptions.allowed_complaints,subscriptions.invoiced_by{
  "customers": [
    {
      "id": "12345",

      "subscriptions": [
        {
          "id": "32134123",
          "state": "active",                 // or suspended/awaiting/ended/stopped
          "business_entity": "DKbusiness",   // included if the business entity has an external ID
          "data": {
            "created": "2026-08-30T23:57:57",
              ":Custom subscription field": "Example text"
          },
          "price": 99.95,                    // included if "subscriptions.price" specified
          "currency": "EUR",                 // included if "subscriptions.price" specified
          "invoiced_by": "E-mail",           // included if "subscriptions.invoiced_by" specified
          "products": [                      // only filled in if there are individual products assigned to the subscription itself
            {
              "id": "9976483",               // id of product assignment
              "name": "Name",
              "external_id": "External ID",
              ":Custom product field": "Some value",
              "data": {
                ":Custom product assignemnt field": "Product value",
              }
            }
          ],
          "periods": [
            {
              "id": "835270",
              "campaign_name": "3 issues",
              "campaign_customer_facing_name": "Beautiful 3 issues",
              "campaign_id": "3i",
              "begin": "2026-08-30T23:57:57",
              "end": null,
              "current": true,               // if the period is currently active
              "subscribed_to": [
                {
                  "name": "Subscription Product Name",
                  "external_id": "External ID",
                }
              ],
              "products": [                  // products assigned to the period, e.g. issues contained in the subscription
                {
                  "id": "19976483",          // id of product assignment
                  "name": "Name",
                  "date": "2026-09-30",
                  "external_id": "External ID",
                }
              ]
            }
          ],
          "payment_agreement": {             // included if "subscriptions.payment_agreement" specified
            "id": "75493106",
            "text": "Mastercard: XX...XX2451 (10/2028)",
            "created": "2024-10-30T23:57:57"
          },
          "group_customer_id": "123456",     // filled in if it's a recipient subscription
          "group_subscription_id": "654321", // points to the group subscription
          "addon_base_subscription_id": "654322", // filled in with base subscription if this is an add-on subscription to the base
          "allowed_complaint_dates": [
            "2026-10-27",
            "2026-10-29"
          ],
          "allowed_complaint_reason_codes": [
            "20",
            "25"
          ]
        }
      ]
    },

    // ...
  ]
}

Products

  • products array with fields=products

    Products that are assigned directly to the customer, i.e. not via a subscription. Products the customer receives through a subscription are listed under the subscription, see subscriptions.

    • id string
      The ID of the product assignment, e.g. "66388".
    • name string
      The product name, e.g. "Voucher product".
    • customer_facing_name string
      The product name shown to customers, e.g. "13 issues of interesting stuff". Included if set.
    • external_id string
      The external ID of the product, e.g. "voucher24". Included if set.
    • created datetime
      When the product was assigned to the customer, as YYYY-MM-DDTHH:MM:SS, e.g. 2026-09-30T23:57:57.
    • distribution_integration string
      The ID of the distribution integration the product is assigned to, if any.
    • data object
      The data of the product assignment, if any, including the custom product assignment fields. Product fields are at the top-level, product assignment fields are in data.
    • business_entity string
      The external ID of the business entity, if it has one, e.g. "DKbusiness".
    • redeemed datetime
      When the voucher was redeemed, as YYYY-MM-DDTHH:MM:SS, e.g. 2026-10-29T23:57:57. Present only for a redeemed voucher product.
    • redeemed_by string
      The customer number of the redeeming customer, e.g. "352". Present only for a redeemed voucher product.
    • redeemed_subscriptions array
      The IDs of the subscriptions created with the voucher, e.g. ["73652"]. Present only for a redeemed voucher product.

    You can set any custom product 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 product 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.

    You can set any custom product assignment 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 product assignment 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.

Here's an example:

GET /api/customers/?id=12346&fields=products{
  "customers": [
    {
      "id": "123456",
      "products": [
        {
          "id": "66388",
          "external_id": "voucher24",
          "name": "Voucher product",
          "created": "2026-09-30T23:57:57",
          ":Custom product field": "Example text",
          // ... more product fields, and if the voucher has been redeemed also redeemed/redeemed_by/redeemed_subscriptions
        }
      ]
    }
  ]
}

Invoices

  • invoices array with fields=invoices

    Invoices, reminders and credit notes for the customer.

    • invoice_number string
      The invoice number, e.g. "1001".
    • invoice_type string
      invoice, reminder or creditnote.
    • invoice_date date
      When the invoice was issued, as YYYY-MM-DD, e.g. 2026-07-30.
    • due date
      When the invoice is due, as YYYY-MM-DD. Included if a due date is set.
    • to_pay decimal

      The amount not yet paid, e.g. 120.95, 0 if it has been paid.

      You might think that you can just check to_pay to determine if the invoice is to be paid. But if an invoice goes unpaid and a reminder is sent, you usually want to show the reminder instead of the invoice, since it may carry a reminder fee still to be paid. So instead inspect to_be_paid to figure out whether an invoice or reminder should be presented for payment.

    • to_be_paid bool
      Whether the invoice should be presented for payment, e.g. true. Set for the most recent due invoices and reminders.
    • reminder integer
      The reminder counter, e.g. 1. Present only on reminders.
    • currency string
      The currency of the amounts, e.g. "EUR".
    • invoiced_by string
      How the invoice was invoiced, e.g. "Payment card".
    • business_entity string
      The external ID of the business entity, if it has one, e.g. "DKbusiness".
    • download_url string with fields=invoices.download_url

      A URL for the invoice PDF, e.g. "https://app.iteras.dk/example/invoice/1001/pdf/?...".

      When you request this, pass preauthseconds to append a token to the download links so they work without logging in for as long as specified.

    • payment_url string with fields=invoices.payment_url
      A URL to pay the invoice, if the invoice is payable.
    • lines array with fields=invoices.lines

      A line on the invoice, describing part of what was invoiced.

      • text string
        The description of the line, e.g. "Subscription 1 year".
      • amount decimal
        The amount with tax, e.g. 120.95.
      • tax_rate decimal
        The tax rate as a fraction, e.g. 0.25 for 25%.
      • tax_amount decimal
        The tax amount, e.g. 24.19.
      • quantity decimal
        The quantity, if not one, e.g. 2.
      • category string

        The line category:

        • subscription
        • product
        • productvoucher
        • none
        • discount
        • fee
        • postage
        • reminderfee
      • period_campaign_id string
        The campaign's self-chosen ID, e.g. "1y". Included for lines tied to a subscription period.
      • period_begin datetime
        When the period begins, as YYYY-MM-DDTHH:MM:SS, e.g. 2026-07-30T23:57:57. Included for lines tied to a subscription period.
      • period_end datetime
        When the period ends, as YYYY-MM-DDTHH:MM:SS, null if ongoing. Included for lines tied to a subscription period.
      • period_id string
        The ID of the period, e.g. "7632784". Included for lines tied to a subscription period.
      • subscription_id string
        The ID of the subscription, e.g. "275498". Included for lines tied to a subscription.
      • product_assignment string
        The ID of the product assignment, if any, e.g. "73529".
      • products array

        The products the line is for, if any, e.g. [{ "id": "12", "name": "Weekend paper" }].

Here's an example where invoices are requested:

GET /api/customers/?id=12345,12346&fields=invoices,invoices.download_url,invoices.payment_url,invoices.lines&iframe=1&preauthseconds=3600{
  "customers": [
    {
      "id": "12345",

      // ...

      "invoices": [
        {
          "invoice_number": "1001",
          "invoice_type": "invoice",
          "invoice_date": "2026-07-30",
          "due": "2026-08-13",
          "invoiced_by": "Payment card",
          "to_pay": 120.95,                   // amount not yet paid (0 if it has been paid)
          "business_entity": "DKbusiness",    // included if the business entity has an external ID
          "download_url": "https://app.iteras.dk/example/iframe/invoice/1001/pdf/?...",
          "payment_url": "https://app.iteras.dk/example/iframe/ordering/summary/?invoice=...",
          "lines": [
            {
              "text": "Subscription 1 year",
              "amount": 120.95,                    // amount with tax
              "tax_rate": 0.25,
              "tax_amount": 24.19,
              "quantity": 2,
              "category": "subscription",
              "period_campaign_id": "1y",
              "period_begin": "2026-07-30T23:57:57",
              "period_end": null,
              "period_id": "7632784",
              "subscription_id": "275498",
              "products": [     // only if the line is associated with specific products
                {
                  "id": "7365",
                  "name": "My product",
                  "customer_facing_name": "The best product",
                  "external_id": "my_prod"
                }
              ]
            },
            {
              "text": "Extra book",
              "amount": 550.00,                    // amount with tax
              "tax_rate": 0.25,
              "tax_amount": 110.00,
              "category": "product",
              "product_assignment": "73529" // ID of the product assignment (if any)
            }
          ]
        },
        {
          "invoice_number": "1005",
          "invoice_type": "reminder",
          "invoice_date": "2026-08-20",
          "reminder": 1,
          "due": "2026-09-03",
          "invoiced_by": "Payment card",
          "to_pay": 170.95,
          "to_be_paid": true,                 // whether to show this as an invoice to pay, see below
          "business_entity": "DKbusiness",    // included if the business entity has an external ID
          "download_url": "https://app.iteras.dk/example/iframe/invoice/1004/pdf/?...",
          "payment_url": "https://app.iteras.dk/example/iframe/ordering/summary/?invoice=...",
          "lines": [
            {
              "text": "Reminder fee",
              "amount": 50.0,
              "tax_rate": 0,
              "tax_amount": 0,
              "category": "reminderfee"
            }
          ]
        },
        {
          "invoice_number": "4",
          "invoice_type": "creditnote",
          "invoice_date": "2026-08-27",
          "to_pay": -20.75,               // as this is a credit note the amount is negative
          "business_entity": "DKbusiness",    // included if the business entity has an external ID
          "download_url": "https://app.iteras.dk/example/invoice/4/pdf/?...",
          "lines": [
            {
              "text": "Credited due to circumstances",
              "amount": -20.75,
              "tax_rate": 0.25,
              "tax_amount": -4.15,
              "quantity": 0.5,
              "category": "subscription",
              "period_campaign_id": "1y",
              "period_begin": "2026-07-30T23:57:57",
              "period_end": null
            }
          ]
        }
      ]
    },

    // ...
  ]
}

Balance

  • balance array with fields=balance

    The customer's balance, paid minus invoiced, per business entity.

    • amount decimal
      The balance, paid minus invoiced, e.g. -99.95. Negative means the customer still owes money; positive means the customer is ahead of what they've been invoiced.
    • currency string
      The currency of the amount, e.g. "EUR".
    • business_entity string
      The external ID of the business entity, if it has one, e.g. "DKbusiness". 
GET /api/customers/?id=12345,12346&fields=balance{
  "customers": [
    {
      "id": "12345",

      "balance": [
        {
          "amount": -99.95,
          "currency": "EUR",
          "business_entity": "DKbusiness"    // included if the business entity has an external ID
        }
      ]
    },

    // ...
  ]
}

Estimated invoicings

  • estimated_invoicings array with fields=estimated_invoicings

    You can ask the system to run a simulation of how it would invoice in the future for the customer and get back an estimate of that as an approximate timestamp and the associated invoice lines. You'll usually want to set estimated_invoicings_until to your time horizon (e.g. 3 months).

    • at datetime
      An estimate of when the invoicing happens, as YYYY-MM-DDTHH:MM:SS.
    • lines array

      The invoice lines that would result.

      • text string
        The description of the line, e.g. "Subscription 1 year".
      • amount decimal
        The amount with tax, e.g. 120.95.
      • tax_rate decimal
        The tax rate, e.g. 0.25.
      • subscription_id string
        The ID of the subscription, if any, e.g. "4321".
      • period_campaign_id string
        The campaign's self-chosen ID, if the line is tied to a subscription, e.g. "1y".
      • quantity decimal
        The quantity, if not one, e.g. 2.

Here's an example:

GET /api/customers/?id=12345,12346&fields=estimated_invoicings&estimated_invoicings_until=2027-01-30{
  "customers": [
    {
      "id": "12345",
      "estimated_invoicings": [
        {
          "at": "2026-12-03T23:57:57",
          "lines": [
            {
              "text": "Subscription 1 year",
              "amount": 120.95,                    // amount with tax
              "tax_rate": 0.25,
              "tax_amount": 24.19,
              "category": "subscription",
              "subscription_id": "4321",
              "period_campaign_id": "1y"
            }
          ]
        }
      ]
    },

    // ...
  ]
}

The estimated_invoicings is left out if the estimation does not find any future invoicings for the customer.

Payments

  • payments array with fields=payments

    The payments from the customer (not refunds).

    • id string
      The ID of the payment, e.g. "824731".
    • amount decimal
      The amount paid, e.g. 175.95.
    • currency string
      The currency of the amount, e.g. "EUR".
    • method string
      The payment method, e.g. "manual".
    • account_date date
      The date the payment is accounted for, as YYYY-MM-DD, e.g. 2026-10-27.
    • registered_date date
      When the payment was registered, as YYYY-MM-DD, e.g. 2026-10-27.
    • business_entity string
      The external ID of the business entity, if it has one, e.g. "DKbusiness".
    • allocated_to array

      What the payment was allocated to, if anything.

      • amount decimal
        The amount allocated, e.g. 100.00.
      • invoice_number string
        The invoice the amount was allocated to, e.g. "73527". 
GET /api/customers/?id=12345,12346&fields=payments{
  "customers": [
    {
      "id": "12345",
      "payments": [
        {
          "amount": 175.95,
          "currency": "DDK",
          "registered_date": "2026-10-27T23:57:57",
          "account_date": "2026-10-27",
          "method": "manual",
          "business_entity": "DKbusiness",   // included if the business entity has an external ID
          "allocated_to": [
            {
              "amount": 100.00,
              "invoice_number": "73527"
            },
          ]
        }
      ]
    },

    // ...
  ]
}

Overrides

  • overrides array with fields=overrides

    Overrides for the customer, e.g. vacations registered for subscriptions or future changes. You should use the filter filter_from to only fetch overrides beginning after that date, e.g. ?filter_from=2026-04-30 - you can also specify a relative date with -6m for "6 months ago"

    • override_id string
      The ID of the override, e.g. "77642".
    • type string
      The type of override, e.g. alternative-delivery or pause-delivery-donate. See the available override types.
    • begin datetime
      When the override begins, as YYYY-MM-DDTHH:MM:SS, e.g. 2026-10-16T23:57:57.
    • end datetime
      When the override ends, as YYYY-MM-DDTHH:MM:SS, e.g. 2026-10-23T23:57:57.
    • subscription_id string
      The ID of the subscription the override applies to, if any, e.g. "1".
    • data object
      Override-specific data, if any, e.g. an alternative delivery address or a donation amount. 
GET /api/customers/?id=12345,12346&fields=overrides&filter_from=2025-10-30  {
  "customers": [
    {
      "id": "12345",
      "overrides": [
        {
          "override_id": "77642",
          "type": "alternative-delivery",
          "begin": "2026-10-16T23:57:57",
          "end": "2026-10-23T23:57:57",
          "subscription_id": "1",
          "data": {
            "address": {
              "name": "Some Test",
              "address": "Somewhere Else\n2412 Northpole",
              "country": "DK"
            }
          }
        },
        {
          "override_id": "77643",
          "type": "pause-delivery-donate",
          "begin": "2026-10-02T23:57:57",
          "end": "2026-10-09T23:57:57",
          "subscription_id": "1",
          "data": {
             "donate_amount": 8.28,
             "credit_percentage": 50,
             "donation_recipient_name": "Private Fund"
          }
        }
      ]
    },
    // ...
  ]
}

Complaints

  • complaints array with fields=complaints

    Distribution complaints by the customer. You should use the filter filter_from to only fetch complaints made on or after that date, e.g. ?filter_from=2026-04-30 - you can also specify a relative date with -6m for "6 months ago"

    • subscription_id string
      The ID of the subscription the complaint is about, if any, e.g. "1".
    • status string
      The status of the complaint, e.g. awaiting.
    • complaint_date date
      When the complaint was made, as YYYY-MM-DD, e.g. 2026-10-29.
    • reason_code string
      The reason code of the complaint, e.g. "20".
    • reason_text string
      A description of the reason, e.g. "Wet newspaper".
    • compensation_action string
      The compensation, e.g. credit or extend. Empty if there is no compensation.
    • compensation_amount decimal
      The credited amount, e.g. 10.25. Included when the compensation is a credit and the complaint is not cancelled.
    • extend_subscription_by integer
      How many issues the subscription is extended by, e.g. 1. Included when the compensation is an extension. 
GET /api/customers/?id=12345,12346&fields=complaints&filter_from=2025-10-30{
"customers": [
  {
    "id": "12345",
      "complaints": [
        {
          "subscription_id": "1",
          "status": "awaiting",
          "complaint_date": "2026-10-29",
          "reason_code": "20",
          "reason_text": "Wet newspaper",
          "compensation_action": "credit", // empty if no compensation
          "compensation_amount": 10.25,    // for 'credit' compensation
          "extend_subscription_by": 1      // for 'extend' compensation
        },
      ]
    },
  ]
}

Segments

  • segments array with fields=segments

    The segments that the customer is in. Segments in Iteras are computed from conditions and are set up inside Iteras.

    • name string
      The name of the segment, e.g. "Blue segment".
    • external_id string
      The external ID of the segment, e.g. "blue". 
GET /api/customers/?id=12345&fields=segments  {
    "customers": [
      {
        "id": "12345",
        "segments": [
          {
            "name": "Blue segment",
            "external_id": "blue"
          }
        ]
      }
    ]
  }

History

  • history array with fields=history

    A human readable log of history related to the customer. Use this only when a human-readable version is needed, not for analysis work — for that, retrieve machine-readable events directly.

    • text string
      A human-readable description of what happened, e.g. "Something happened".
    • timestamp datetime
      When it happened, as YYYY-MM-DDTHH:MM:SS, e.g. 2026-07-30T23:57:58.
    • by string
      Who did it, e.g. "somebody@example.com". 
GET /api/customers/?id=12345,12346&fields=history&filter_from=2026-04-30{
  "customers": [
    {
      "id": "12345",

      // ...

      "history": [
        {
          "text": "Something else happened",
          "timestamp": "2026-06-30T23:57:58",
          "by": "System"
        },
        {
          "text": "Something happened",
          "timestamp": "2026-07-30T23:57:58",
          "by": "somebody@example.com"
        }
      ]

    },

    // ...
  ]
}

Extra fields

Some fields have extra formatting options you can use. You request them with an extrafield parameter. The format is field_name:formattingoption. In case you want to avoid having a field with a ":" in it, you can name the resulting field with "=" like field_name:formattingoption=formatted_field_name. You can specify extrafield multiple times to add more fields.

Here's an example:

GET /api/customers/?id=12345&extrafield=delivered_to%3Aformatted&extrafield=delivered_to%3Apostcode%3Dpostcode{
  "customers": [
    {
      "id": "12345",
      "data": {
         "delivered_to:formatted": "John Doe\nSome Road 123\n1000 København K\nDanmark",
         "postcode": "1000",
         // ...
      }
    }
  ]
}

Currently address fields support the following formatting options:

  • "formatted" - multi-line textual representation of name, company, address and country
  • "postcode" - use the address parser in Iteras to try to extract the postcode
  • "address:split" - use the address parser in Iteras to try to split the address itself into components

Pagination

To avoid having to handle a too large JSON document both in the sending and receiving end, the results are divided into pages. You can set the page size with max_results. If a query finds more results than what fits into the first page, the returned result contains a next_url where you can retrieve the next page, which may in turn have a next_url. Here's an example with 103 customers and a page size of 100:

GET /api/customers/?max_results=100{
  "customers": [ /* customer 1 to customer 100 */ ],
  "next_url": "https://app.iteras.dk/api/customers/?max_results=100&from=101"
}

Then when you query next_url, you get the next page of customers - in this example this is the last page of results, so there is no next_url:

GET /api/customers/?max_results=100&from=101{
  "customers": [ /* customer 101 to customer 103 */ ]
}

If you write code that may return a lot of customers, you should set max_results to a low value while you test your code to make sure you can handle the pagination correctly.

The from parameter is an internal parameter used for the pagination. Currently it's just the customer number to start at.

Errors

An invalid filter, filter_subscriptions or extrafield, or a missing preauthseconds when requesting preauth_token, returns a plain text HTTP 400 error.