# Invoice

POST `https://app.iteras.dk/api/customers/invoice/`

The API key must allow "Change subscriber data".

Invoices a number of invoice lines on a customer.

## Parameters

- `id` (string, required): ID of the customer.
- `business_entity` (string): The external ID of the business entity to invoice for. Must be specified if `subscription_id` is not given.
- `subscription_id` (string): If the invoice lines concern a certain subscription.
- `period` (string, Defaults to `current`): Either `current` or the index of the period, with 1 being the oldest period, in case a `subscription_id` is specified, e.g. `"period": 1`. Invoice lines never bind to the subscription directly but always a specific period of the subscription.
- `lines` (array, required): The lines to invoice, each an object with `text`, `amount`, `currency` and `tax_rate`.
- `due` (date): Date the invoice is due, as `YYYY-MM-DD`. If not filled in, the due date is calculated from the internal rules in Iteras.
- `send` (bool, Defaults to `true`): Set to `false` to prevent the invoice being sent. This can be useful when importing old debt.
- `note` (string): Internal note attached to the invoice.
- `exclude_from_webhooks` (bool, Defaults to `false`): Set to `true` to keep every event the request causes from being sent to webhooks, invoice and payment events included, e.g. `"exclude_from_webhooks": true`. The events are still added to the history.

Each element of `lines` is an object with the following attributes:

- `text` (string, required): Description of what is invoiced, may contain newlines, e.g. `Extra service\nLine 2`.
- `amount` (integer, required): Integer amount (send €10.50 as `1050`), including any tax.
- `currency` (string, required): Three-letter ISO currency code, e.g. `EUR`. The currency must match the invoice/business entity.
- `tax_rate` (number, required): The tax rate applied to the line, e.g. `0.25` for 25% tax. Set it to 0 for lines that are exempt from tax.

## Examples

Invoice two lines on a subscription period:

```http
POST /api/customers/invoice/ HTTP/1.1
Content-Type: application/json
```

```json
{
  "id": "12345",
  "lines": [{
    "text": "Product A",
    "amount": 10050,
    "currency": "DKK",
    "tax_rate": 0.25
  }, {
    "text": "Shipping",
    "amount": 2050,
    "currency": "DKK",
    "tax_rate": 0
  }],
  "subscription_id": "32142532",
  "due": "2026-12-22"
}
```

Invoice a balance from an old system, without sending it:

```http
POST /api/customers/invoice/ HTTP/1.1
Content-Type: application/json
```

```json
{
  "id": "12345",
  "lines": [{
    "text": "Unpaid amount from Jan-Feb",
    "amount": 56095,
    "currency": "DKK",
    "tax_rate": 0.25
  }],
  "business_entity": "DKbranch",
  "due": "2026-12-22",
  "send": false,
  "note": "Balance from old system"
}
```

## Return value

On success the endpoint returns the number of the new invoice:

```json
{ "invoice_number": "1007" }
```

## Errors

Invalid requests due to programming error, e.g. invalid JSON, returns 400. This also covers a missing `lines` array, a `tax_rate` outside the range 0-1, and more than one distinct non-zero `tax_rate` on an invoice.

A well-formed operation where a supplied value is invalid is not executed and returns an HTTP 422 error. The response is a JSON object with the errors keyed by the field they concern, e.g. a currency that doesn't match the business entity:

```json
{
  "lines": ["Invalid currency: EUR"]
}
```

Errors that are not specific to a field are returned with the empty string as key, e.g. an unknown subscription, period or business entity:

```json
{
  "": ["Business entity does not exist."]
}
```