DOCSEARCHbyAlgolia
Submit Docs

Iteras API Documentation

website·Indexed 35 days ago

https://app.iteras.dk/api/docs/server/gettingstarted/

Developer documentation for Iteras, featuring a JavaScript API for paywalls, iframes, and UI theming, as well as a server-side API for managing customers, subscriptions, orders, and financial reporting. Includes guides on identity and access management, data migration, synchronization with external systems, and webhook configuration.

Tokens
23.2K
Snippets
107
Records
143
Agent score
66%

What's inside Iteras

  1. Overview of the Iteras invoicing delivery flow

    Iteras allows the integration of custom delivery methods for invoices. The general workflow is as follows:

    1. Iteras identifies subscriptions with uninvoiced periods and creates a delivery record for each invoice.
    2. The integration fetches a batch of waiting deliveries via the API.
    3. The integration sends the invoices (either as a batch or individually).
    4. The integration reports the success or failure of each delivery back to Iteras.

    If a delivery fails, Iteras can either retry the delivery based on a provided schedule or fall back to another delivery method.

  2. Retrieve business policies via the /api/policies/ endpoint

    The /api/policies/ endpoint allows you to retrieve information about business policies, which contain business intelligence settings and policies. The endpoint uses the GET method and returns an object containing an array of policy information.
    {
  "policies": [
    {
      "id": "6543",
      "name": "Royal customers",
      "external_id": "Royals",
      "active": true,
      "lines": [
        {
          "text": "Special discount",
          "percentage": -0.10
        }
      ]
    }
  ]
}

  3. Core Iteras business concepts

    Understanding these entities is key to using the API:

    • Customer: The basic entity.
    • Subscription: A customer can have multiple subscriptions to products.
    • Period: Subscriptions are divided into consecutive billing/tracking periods.
    • Campaign: Configures billing, price, and products for a period; determines if a subscription renews or stops when a period ends.
    • Invoice Line Specifications: Define billing rules, which are instantiated during invoicing. Amounts are always returned inclusive of tax (VAT/moms).

  4. Retrieve order information using the Orders API

    The /api/orders/ endpoint is used to retrieve information about orders placed via the UI or the place order API. It returns orders in any state, including completed, awaiting approval, or pending payment.

    Key Constraints:

    • A maximum of 10,000 orders are returned per request. Use created_before or created_after to paginate or filter large datasets.
    • Only fields that were filled in during the ordering process are returned in the JSON response.
    • The newest orders are returned first.
    # Example: Get orders for a specific customer created after a certain date
GET /api/orders/?customer=452&created_after=2026-06-25

  5. Retrieve distribution day schedules

    The /api/distributiondays/ endpoint retrieves information about specific distribution days (e.g., whether a physical product is distributed on a given date). The returned data depends on the specific distribution integration setup in Iteras.

    Request Parameters (GET):

    • start_date: The start date for the range, inclusive (e.g., 2023-01-01).
    • end_date: The end date for the range, inclusive (e.g., 2023-12-31).

    Return Value: An object containing a distributiondays array. Each element includes the date and a data object containing field definition values such as publication_day.

    {
  "distributiondays": [
    {
        "date": "2023-05-03",
        "data": {
            "publication_day": true
        }
    },
    {
        "date": "2023-05-04",
        "data": {
            "publication_day": true,
            "interpreted_as_weekdays": [
                4,
                5
            ]
        }
    },
    {
        "date": "2023-05-05",
        "data": {
            "publication_day": false
        }
    }
  ]
}

  6. Choose a branding system for Customer UI

    Iteras provides five branding systems to control the appearance of self-service pages:

    • Neutral, Modern, Classic: Curated presets with specific typography, shadows, and borders. You can optionally set a primary color to tint CTAs, links, and accents.
    • Simple: A basic configuration for primary color, page background, corner style, and font type.
    • Advanced: Full control via raw CSS variable declarations. This mode allows for precise customization using the Iteras CSS variable system.

  7. Retrieve active campaigns via the /api/campaigns/ endpoint

    The /api/campaigns/ endpoint is used to retrieve information about active campaigns in Iteras. A campaign defines what a customer receives in a single period, the billing method, and renewal settings. The endpoint returns an object containing an array of campaign data. Note that only fields that have been filled in within Iteras are returned in the API response.
    GET /api/campaigns/

  8. Retrieve field definitions via the /api/fields/ endpoint

    Use the /api/fields/ endpoint with a GET request to retrieve information about the fields defined in Iteras. The response returns an object containing a fields array of field definitions, including the field name, ID, and type. For fields of type choice, a choices array is provided containing the available options and their identifiers.
    {
  "fields": [
    {
      "name": "Title",
      "id": ":Title",
      "type": "text"
    },
    {
      "name": "Subscription type",
      "id": "subscription_type",
      "type": "choice",
      "choices": [
        {
          "name": "Professionel",
          "identifier": "pro"
        },
        {
          "name": "Personal",
          "identifier": "personal"
        },
        {
          "name": "Business",
          "identifier": "business"
        }
      ]
    }
  ]
}

  9. Retrieve system changes using the Events API

    The /api/events/ endpoint allows developers to retrieve raw data and the associated new state for changes occurring in Iteras (e.g., customer creation, subscription status changes). Events are returned in chronological order (oldest first) and each contains an event_id, timestamp, and event type. This endpoint is primarily used for synchronizing external systems with Iteras data.

  10. Implement server-side paywall validation for higher security

    The JavaScript paywall API is a client-side solution and can be bypassed by skilled users. For high-security requirements, implement a server-side check of the 'pass cookie'. The server should be configured to prevent content delivery to users who do not possess a valid pass cookie. This is recommended if client-side enforcement is insufficient for your target audience.

  11. Insert Iteras iframes into a webpage

    Iteras iframe methods return an HTML string. You can insert this string directly into the DOM using document.write or a framework like jQuery. The iteras.js script must be included on the page for the iframe to automatically resize its height based on content.
    <!-- Direct insertion -->
<script>
  document.write(Iteras.orderingiframe({ profile: "myprofile", orderingid: "XXXXX" }));
</script>

<!-- Using jQuery -->
<div id="ordering-iframe-container"></div>
<script>
  $(function () {
    $("#ordering-iframe-container").append(Iteras.orderingiframe({ profile: "myprofile", orderingid: "XXXXX" }));
  });
</script>

  12. Generate and use pre-authentication tokens for SSO

    To implement Single Sign-On (SSO) and bypass the login screen in Iteras self-service iframes, request a pre-authentication token by adding the preauthseconds parameter (specifying the token's validity duration in seconds) to the /api/authenticatecustomer/ POST request.

    If authenticated, the response will include a preauth token. This token can be used in two ways:

    1. Via JS API: Pass the token to the Iteras.selfserviceiframe function.
    2. Via URL Parameter: Append the token as a GET parameter iteraspreauth to a URL. If that page contains an embedded self-service iframe or is a stand-alone self-service page, Iteras will automatically use the token to log the user in.
    // 1. Requesting the token (POST parameters)
// id=12345&password=secret&preauthseconds=3600

// 2. Using the token in the JS API
Iteras.selfserviceiframe({
  profile: "myprofile",
  preauth: "Azxd123:JOIj123:JOjOIJASDF"
});

// 3. Using the token via URL redirect
// https://example.com/otherpage/?iteraspreauth=Azxd123%3AJOIj123%3AJOjOIJASDF