Create a draft invoice

curl --request POST \
  --url https://api.envoi.no/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "clientId": "c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e",
  "dueDate": "2026-10-13",
  "reference": "Ordre 5512",
  "notes": "Takk for handelen!",
  "lines": [
    {
      "description": "Kaffebønner 1 kg",
      "quantity": 4,
      "unitPrice": 250,
      "vatCode": 3
    }
  ]
}
'

import requests

url = "https://api.envoi.no/v1/invoices"

payload = {
    "clientId": "c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e",
    "dueDate": "2026-10-13",
    "reference": "Ordre 5512",
    "notes": "Takk for handelen!",
    "lines": [
        {
            "description": "Kaffebønner 1 kg",
            "quantity": 4,
            "unitPrice": 250,
            "vatCode": 3
        }
    ]
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    clientId: 'c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e',
    dueDate: '2026-10-13',
    reference: 'Ordre 5512',
    notes: 'Takk for handelen!',
    lines: [{description: 'Kaffebønner 1 kg', quantity: 4, unitPrice: 250, vatCode: 3}]
  })
};

fetch('https://api.envoi.no/v1/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.envoi.no/v1/invoices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'clientId' => 'c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e',
    'dueDate' => '2026-10-13',
    'reference' => 'Ordre 5512',
    'notes' => 'Takk for handelen!',
    'lines' => [
        [
                'description' => 'Kaffebønner 1 kg',
                'quantity' => 4,
                'unitPrice' => 250,
                'vatCode' => 3
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.envoi.no/v1/invoices"

	payload := strings.NewReader("{\n  \"clientId\": \"c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e\",\n  \"dueDate\": \"2026-10-13\",\n  \"reference\": \"Ordre 5512\",\n  \"notes\": \"Takk for handelen!\",\n  \"lines\": [\n    {\n      \"description\": \"Kaffebønner 1 kg\",\n      \"quantity\": 4,\n      \"unitPrice\": 250,\n      \"vatCode\": 3\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.envoi.no/v1/invoices")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"clientId\": \"c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e\",\n  \"dueDate\": \"2026-10-13\",\n  \"reference\": \"Ordre 5512\",\n  \"notes\": \"Takk for handelen!\",\n  \"lines\": [\n    {\n      \"description\": \"Kaffebønner 1 kg\",\n      \"quantity\": 4,\n      \"unitPrice\": 250,\n      \"vatCode\": 3\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.envoi.no/v1/invoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"clientId\": \"c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e\",\n  \"dueDate\": \"2026-10-13\",\n  \"reference\": \"Ordre 5512\",\n  \"notes\": \"Takk for handelen!\",\n  \"lines\": [\n    {\n      \"description\": \"Kaffebønner 1 kg\",\n      \"quantity\": 4,\n      \"unitPrice\": 250,\n      \"vatCode\": 3\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "8b6f2a4e-1c3d-4e5f-9a7b-2c4d6e8f0a12",
  "number": null,
  "type": "invoice",
  "status": "draft",
  "kid": null,
  "issueDate": "2026-09-29",
  "dueDate": "2026-10-13",
  "paidAt": null,
  "reference": "Ordre 5512",
  "notes": "Takk for handelen!",
  "client": {
    "id": "c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e",
    "name": "Fjordkaffe AS",
    "email": "post@fjordkaffe.no",
    "address": "Kaigata 1",
    "postalCode": "5003",
    "city": "Bergen",
    "orgNumber": "912345688",
    "country": "NO",
    "vatNumber": null
  },
  "currency": "NOK",
  "subtotal": 1000,
  "vat": 250,
  "total": 1250,
  "paidAmount": 0,
  "outstandingAmount": 1250,
  "creditedAmount": 0,
  "lines": [
    {
      "description": "Kaffebønner 1 kg",
      "quantity": 4,
      "unitPrice": 250,
      "vatRate": 25,
      "vatCode": 3,
      "lineTotal": 1000,
      "vatAmount": 250
    }
  ],
  "payments": [],
  "createdAt": "2026-09-29T10:15:00Z",
  "updatedAt": "2026-09-29T10:15:00Z"
}

Invoices

Create a draft invoice

Creates a draft, with the same rules as creating an invoice in the Envoi app. Nothing is numbered, booked or sent until you call POST /v1/invoices/{id}/send.

Name the customer by clientId (a client in this account) or inline in client, not both. An inline client is matched against the register (by organisation number, then email) and added to it when it is not there, as in the app. dueDate is required. A line may name its VAT by vatCode (a SAF-T sales code) or vatRate, or both if they agree; with neither, the account’s default VAT rate applies.

POST

https://api.envoi.no

invoices

Create a draft invoice

curl --request POST \
  --url https://api.envoi.no/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "clientId": "c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e",
  "dueDate": "2026-10-13",
  "reference": "Ordre 5512",
  "notes": "Takk for handelen!",
  "lines": [
    {
      "description": "Kaffebønner 1 kg",
      "quantity": 4,
      "unitPrice": 250,
      "vatCode": 3
    }
  ]
}
'

import requests

url = "https://api.envoi.no/v1/invoices"

payload = {
    "clientId": "c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e",
    "dueDate": "2026-10-13",
    "reference": "Ordre 5512",
    "notes": "Takk for handelen!",
    "lines": [
        {
            "description": "Kaffebønner 1 kg",
            "quantity": 4,
            "unitPrice": 250,
            "vatCode": 3
        }
    ]
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    clientId: 'c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e',
    dueDate: '2026-10-13',
    reference: 'Ordre 5512',
    notes: 'Takk for handelen!',
    lines: [{description: 'Kaffebønner 1 kg', quantity: 4, unitPrice: 250, vatCode: 3}]
  })
};

fetch('https://api.envoi.no/v1/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.envoi.no/v1/invoices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'clientId' => 'c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e',
    'dueDate' => '2026-10-13',
    'reference' => 'Ordre 5512',
    'notes' => 'Takk for handelen!',
    'lines' => [
        [
                'description' => 'Kaffebønner 1 kg',
                'quantity' => 4,
                'unitPrice' => 250,
                'vatCode' => 3
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.envoi.no/v1/invoices"

	payload := strings.NewReader("{\n  \"clientId\": \"c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e\",\n  \"dueDate\": \"2026-10-13\",\n  \"reference\": \"Ordre 5512\",\n  \"notes\": \"Takk for handelen!\",\n  \"lines\": [\n    {\n      \"description\": \"Kaffebønner 1 kg\",\n      \"quantity\": 4,\n      \"unitPrice\": 250,\n      \"vatCode\": 3\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.envoi.no/v1/invoices")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"clientId\": \"c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e\",\n  \"dueDate\": \"2026-10-13\",\n  \"reference\": \"Ordre 5512\",\n  \"notes\": \"Takk for handelen!\",\n  \"lines\": [\n    {\n      \"description\": \"Kaffebønner 1 kg\",\n      \"quantity\": 4,\n      \"unitPrice\": 250,\n      \"vatCode\": 3\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.envoi.no/v1/invoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"clientId\": \"c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e\",\n  \"dueDate\": \"2026-10-13\",\n  \"reference\": \"Ordre 5512\",\n  \"notes\": \"Takk for handelen!\",\n  \"lines\": [\n    {\n      \"description\": \"Kaffebønner 1 kg\",\n      \"quantity\": 4,\n      \"unitPrice\": 250,\n      \"vatCode\": 3\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "8b6f2a4e-1c3d-4e5f-9a7b-2c4d6e8f0a12",
  "number": null,
  "type": "invoice",
  "status": "draft",
  "kid": null,
  "issueDate": "2026-09-29",
  "dueDate": "2026-10-13",
  "paidAt": null,
  "reference": "Ordre 5512",
  "notes": "Takk for handelen!",
  "client": {
    "id": "c2a9d4e1-5b7f-4c3a-8e6d-1f2a3b4c5d6e",
    "name": "Fjordkaffe AS",
    "email": "post@fjordkaffe.no",
    "address": "Kaigata 1",
    "postalCode": "5003",
    "city": "Bergen",
    "orgNumber": "912345688",
    "country": "NO",
    "vatNumber": null
  },
  "currency": "NOK",
  "subtotal": 1000,
  "vat": 250,
  "total": 1250,
  "paidAmount": 0,
  "outstandingAmount": 1250,
  "creditedAmount": 0,
  "lines": [
    {
      "description": "Kaffebønner 1 kg",
      "quantity": 4,
      "unitPrice": 250,
      "vatRate": 25,
      "vatCode": 3,
      "lineTotal": 1000,
      "vatAmount": 250
    }
  ],
  "payments": [],
  "createdAt": "2026-09-29T10:15:00Z",
  "updatedAt": "2026-09-29T10:15:00Z"
}

Authorizations

Authorization

string

header

required

OAuth 2.0 client credentials. The token request also needs the audience form field (the Account ID), which OAuth tooling does not always send; see POST /v1/oauth/token.

Headers

Idempotency-Key

string

required

Required on every POST, at most 255 characters. Use a new UUID for each logical operation. The first request with a key runs, and its answer (any status below 500) is stored for 7 days. A retry with the same key, method, path and body gets the stored answer again with Idempotency-Replayed: true, and nothing runs twice. The same key with a different body or path is 422 idempotency-key-reused; the same key while the first request is still running is 409 idempotency-key-in-progress. A 5xx answer is not stored, so the same key may be retried. A key belongs to the API client's grant (one environment).

Maximum string length: 255

Body

application/json

The draft.

A new draft invoice. Send it with POST /v1/invoices/{id}/send.

dueDate

string<date>

required

The due date. Required.

lines

object[]

required

The invoice lines. Required; at least one.

Minimum array length: 1

Show child attributes

clientId

string<uuid> | null

A client in this account's register. Give this or client, not both.

client

object

A client given inline on a new invoice (when no clientId is sent).

Show child attributes

reference

string | null

Your reference, for example an order number.

notes

string | null

A note printed on the invoice.

Response

The draft invoice.

An invoice or credit note.

string<uuid>

required

The invoice's id.

type

string

required

invoice or credit_note.

status

string

required

draft, sent, viewed, paid, overdue, reminded, collection_warning, credited or bounced.

issueDate

string<date>

required

The invoice date.

dueDate

string<date>

required

The due date.

reference

string

required

Your reference, for example an order number; empty when none.

client

object

required

The client on an invoice: the name and address the invoice is made out to.

Show child attributes

currency

string

required

Always NOK in v1.

subtotal

number

required

Total without VAT.

vat

number

required

Total VAT.

total

number

required

Total with VAT.

paidAmount

number

required

How much has been paid.

outstandingAmount

number

required

How much is still owed.

lines

object[]

required

The invoice lines.

Show child attributes

payments

object[]

required

The payments recorded on it.

Show child attributes

createdAt

string<date-time>

required

When it was created (UTC).

updatedAt

string<date-time>

required

When it last changed (UTC).

creditedAmount

number

required

The issued credit notes against the invoice; outstandingAmount is net of it.

number

string | null

The invoice number, or null on a draft (it gets one when it is sent).

kid

string | null

The KID (payment reference), or null when there is none (always on a draft).

paidAt

string<date> | null

The date it was paid in full, or null.

notes

string | null

A note printed on the invoice, or null.

Get started

Authentication

Invoices

Customers

Accounting

Create a draft invoice

Authorizations

Headers

Body

Response