Developer documentation

Invoice lines format

The invoice lines format is used in several places to describe something to invoice, i.e. not yet invoiced. It's an array of objects, where each object has a description and an amount and tax information. Percentage lines without amount for discounts or fees are also possible. The format is used for the invoice API, for campaigns, in business policies and you can add custom fields in Iteras with invoice lines.

Here's a basic example:

[
  {
    "text": "3 months",
    "amount": 24950,
    "tax_rate": 0.25
  },
  {
    "text": "Discount",
    "percentage": -0.10
  }
]

Options

  • text string required
    Description shown on the invoice, e.g. 3 months of Product.
  • amount integer required
    Integer amount in cents (send €10.50 as 1050). The currency used is the currency defined on the related business entity. Required unless the line is a percentage line.
  • amount_includes_tax bool Defaults to true
    Whether the given amount includes tax or not. Sometimes it's easier to work with prices without tax and have Iteras calculate and add it automatically when invoicing.
  • tax_rate number required
    Tax rate that the line follows, e.g. 0.25 for 25%. Set it to 0 for tax-exempt lines. Required unless the line is a percentage line.

Extended options for extra configuration:

  • affected_by_percentage bool Defaults to true
    Set to false on an amount line to leave it out of the calculations when calculation the amount for percentage lines.
  • scale_with array

    Set scale_with to multiply the amount when the line is invoiced, for postage or a price that follows what is delivered. If left out, the amount is invoiced as given.

    • quantity multiplies the amount by the quantity delivered.
    • assignments multiplies the amount by the number of product assignments in the campaign period.

    Both can be given.

  • extra_info array

    Whether to automatically append extra information lines to the description upon issuing the invoice. One or more of:

    • period - append start and duration of the invoiced period
    • fields - appen the value of fields that are set to appear on invoice lines
    • delivery_name - append name of the customer if different from payer
    • delivery_address - append name and address of the customer if different from payer
    • customer_number - append customer number if different from payer
    • active_group_recipients - append active group recipients

    On campaign invoice lines you'd usually add extra information, e.g. at least ["period"], to the first line.

  • line_category string
    Override category for reporting, one of subscription, product, productvoucher, discount, fee, postage, reminderfee or none. If not given, defaults to what fits the context the line is used in.
  • conditions array

    Conditions that decide whether the line is added, see the conditions format. The evaluation context here is the invoice line that could be added, so a customer:satisfies condition applies to the line's customer, and invoiceline:subscriptionperiod and invoiceline:productassignment assert the existence of and filter on the line's subscription period and product assignment respectively. For instance, here's how to add the line only for customers not in Denmark:

    [
  {
    "condition_type": "customer:satisfies",
    "conditions": [
      {
        "condition_type": "customer:field",
        "field": "country",
        "operator": "notin",
        "options": ["DK"]
      }
    ]
  }
]
  • valid_from date
    If you want to restrict when the line should be added, set to the first day the line applies, as YYYY-MM-DD, e.g. 2026-11-21.
  • valid_to date
    If you want to restrict when the line should be added, set to the day the line should no longer apply, as YYYY-MM-DD, e.g. 2026-12-21. The date is exclusive, so a line with valid_to set to August 1st applies up to and including July 31st.
  • volume_prices array
    Instead of a single amount the line can carry a set of price levels, each with a text, a from_count (the size the level starts at), a price and an optional price_includes_tax. The prices should always start with an initial level with from_count 1. Requires volume_price_based_on. See Volume prices.
  • volume_price_based_on string
    Required when volume_prices are given. What the size counts:
    • subscription:grouprecipientcount - the number of receiver subscriptions in the group
    • subscription:policysubscriptioncount - the number of subscriptions on the same policy
  • override_type string
    For controlling how the line behaves with respect to the other lines, for when invoice lines are injected into the invoicing process, e.g. from a business policy or invoice lines given on a subscription. One of:
    • override_invoicelines - replace the other lines
    • override_invoicelines_if_conditions_apply - replace them only when the line's conditions are met
    • preceding_invoicelines - place the line before the other lines
    • succeeding_invoicelines - place the line after the other lines
  • unique_on_invoice bool
    Set to true to allow the line only once on an invoice. This can sometimes be useful for fees.

Changing prices over time

With valid_from and valid_to new prices can be pre-planned. To raise the price of a monthly subscription one month from now, use one line that stops and another that starts the same day:

[
  {
    "text": "Monthly subscription",
    "amount": 9900,
    "tax_rate": 0.25,
    "valid_to": "2026-11-21"
  },
  {
    "text": "Monthly subscription",
    "amount": 10900,
    "tax_rate": 0.25,
    "valid_from": "2026-11-21"
  }
]

Make sure the ranges meet. valid_to is exclusive, so a gap between the dates would leave the subscription free for that time. There's an automation available inside Iteras for automatically changing the prices of campaigns using this mechanism.

Volume prices

A line can carry a set of volume prices, one per volume size, instead of a single amount:

[{
  "text": "Employees",
  "tax_rate": 0.25,
  "volume_price_based_on": "subscription:grouprecipientcount",
  "volume_prices": [
    { "text": "1 employee", "from_count": 1, "price": 0 },
    { "text": "2-5 employees", "from_count": 2, "price": 9900 },
    { "text": "6+ employees", "from_count": 6, "price": 7900 }
  ]
}]

Percentage lines

It's possible to specify lines as a percentage of the other lines instead of a fixed amount. A line with a percentage and no amount is a percentage line. The percentage is applied to the total of the amount lines on the invoice that are affected by a percentage, i.e. every line unless it sets affected_by_percentage to false. Lines are grouped by tax rate and associated products, and a percentage line takes the tax rate of the group it applies to.

  • percentage number required
    The signed fraction applied, e.g. -0.10 for a 10% discount or 0.05 for a 5% fee. A percentage line has no amount and tax_rate of its own. 
[{
  "text": "Welcome discount",
  "percentage": -0.10
}]