Klantly Developers

API-referentie

Facturen

Facturen en creditnota's met hun regels en betalingen: opstellen, bijwerken zolang ze concept zijn, versturen, annuleren, betalingen vastleggen, crediteren, en de pdf of de betaallink ophalen.

Endpoints

Facturen opvragen

GET /api/v1/invoices

Een lijst van facturen, nieuwste eerst, met hun regels en de geregistreerde betalingen. Filter op status, klant of wijzigingsdatum. Met filter[status]=paid en filter[updated_since] haal je op wat er sinds je vorige synchronisatie is betaald. Creditnota's staan in dezelfde lijst (type credit_note, met negatieve bedragen); met filter[type] haal je alleen facturen of alleen creditnota's op.

Scope
invoices.read — Facturen lezen, met regels, bedragen, betalingen en de klantgegevens erop
Vereiste functie
invoices

Queryparameters

NaamTypeOmschrijving
limit integer Aantal resultaten per pagina. van 1 tot 100 · standaard: 50
cursor string De next_cursor of prev_cursor uit meta van het vorige antwoord.
sort string Het veld waarop je sorteert; een min-teken ervoor is aflopend. Welke velden je kunt kiezen en wat de standaard is, staat bij deze parameter. een van: -created_at, created_at, -updated_at, updated_at · standaard: -created_at
filter[status] string Alleen facturen met deze status, bijvoorbeeld paid, overdue of credited. een van: draft, sent, viewed, paid, partial, overdue, cancelled, refunded, credited
filter[type] string Alleen facturen (invoice) of alleen creditnota's (credit_note). Zonder dit filter komen ze allebei mee. een van: invoice, credit_note
filter[customer_id] string (uuid) Alleen wat bij deze klant hoort.
filter[updated_since] string (date-time) Alleen wat sinds dit tijdstip is gewijzigd: ISO 8601 mét tijdzone, bijvoorbeeld 2026-09-14T10:15:00Z. Handig om te synchroniseren. Neem een overlap van een paar minuten op je vorige moment, omdat de klok van jouw systeem en die van Klantly niet exact gelijk lopen, en omdat een wijziging vlak na je vorige moment anders net buiten de boot valt. De grens is inclusief: iets dat exact op dit tijdstip is gewijzigd, doet mee.

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/invoices?filter[status]=paid&sort=-updated_at" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'invoices', [
    'query' => [
        'filter[status]' => 'paid',
        'sort' => '-updated_at',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/invoices?filter[status]=paid&sort=-updated_at', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/invoices",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    params={
        "filter[status]": "paid",
        "sort": "-updated_at"
    },
)
data = response.json()["data"]

Antwoord 200

Het antwoord is een lijst met cursorpaginering: data bevat de objecten, meta de paginering.

Voorbeeldantwoord
{
  "data": [
    {
      "object": "invoice",
      "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
      "number": "FAC-00042",
      "type": "invoice",
      "status": "sent",
      "title": "Veranda 400 × 300",
      "description": null,
      "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
      "customer": {
        "type": "business",
        "name": "De Vries Bouw",
        "email": "jan@example.com",
        "phone": "+31 6 12345678",
        "address": "Dorpsstraat 1",
        "postal_code": "3511 AB",
        "city": "Utrecht",
        "country": "NL",
        "company_name": "De Vries Bouw",
        "vat_number": null,
        "coc_number": null
      },
      "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
      "deal_id": null,
      "language": "nl",
      "currency": "EUR",
      "invoice_date": "2026-09-16",
      "due_date": "2026-10-16",
      "payment_term_days": 30,
      "is_term_invoice": false,
      "term_percentage": null,
      "term_amount": null,
      "terms_conditions": null,
      "notes": null,
      "outro_text": null,
      "hide_line_amounts": false,
      "discount_percentage": "0.00",
      "discount_amount": "0.00",
      "discount_description": null,
      "subtotal": "2450.00",
      "tax_amount": "514.50",
      "total": "2964.50",
      "amount_paid": "0.00",
      "amount_due": "2964.50",
      "sent_at": null,
      "viewed_at": null,
      "paid_at": null,
      "cancelled_at": null,
      "credited_invoice_id": null,
      "credited_invoice_number": null,
      "credit_reason": null,
      "refund_amount": null,
      "refunded_at": null,
      "credit_note_state": null,
      "credited_amount": "0.00",
      "credit_note_ids": [],
      "items": [
        {
          "object": "invoice_item",
          "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
          "type": "product",
          "name": "Veranda",
          "description": null,
          "sku": null,
          "quantity": "1.00",
          "unit": "stuk",
          "unit_price": "2450.00",
          "unit_price_incl": null,
          "discount_percentage": "0.00",
          "discount_amount": "0.00",
          "discount_description": null,
          "line_total": "2450.00",
          "line_total_incl": null,
          "is_taxable": true,
          "tax_rate": "21.00",
          "credited_item_id": null
        }
      ],
      "payments": [
        {
          "object": "invoice_payment",
          "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
          "amount": "2964.50",
          "type": "full",
          "status": "paid",
          "payment_method": "bank_transfer",
          "description": null,
          "paid_at": "2026-09-16T10:15:00Z",
          "created_at": "2026-09-16T10:15:00Z"
        }
      ],
      "created_at": "2026-09-14T10:15:00Z",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Factuur ophalen

GET /api/v1/invoices/{invoice}

Eén factuur op id, met regels, bedragen en betalingen. Het antwoord bevat een ETag die je bij bijwerken in If-Match kunt meesturen.

Scope
invoices.read — Facturen lezen, met regels, bedragen, betalingen en de klantgegevens erop
Vereiste functie
invoices

Padparameters

NaamTypeOmschrijving
invoice verplicht string (uuid) De id (UUID) van de factuur.

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "term_amount": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00",
        "credited_item_id": null
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Factuur aanmaken

POST /api/v1/invoices

Maakt een factuur aan bij een klant, altijd als concept. Klantly geeft hem een nummer en rekent de totalen uit; naam, adres en contactgegevens komen van de klant. Met quote_id koppel je de factuur aan een offerte.

Scope
invoices.write — Facturen aanmaken (ook van een offerte) en wijzigen (alleen concepten), annuleren, betalingen registreren, crediteren en een terugbetaling vastleggen
Vereiste functie
invoices

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Body (JSON)

VeldTypeOmschrijving
customer_id verplicht string (uuid) De klant. Verplicht bij aanmaken; naam, adres en contactgegevens komen van de klant.
title verplicht string Titel van de factuur. Verplicht bij aanmaken. maximaal 255 tekens
items verplicht array De regels (maximaal 200). Bij invoer: een lijst met per regel name (verplicht) en optioneel type, description, sku, quantity, unit, unit_price, unit_price_incl, discount_percentage, discount_amount, discount_description, tax_rate en is_taxable. Ze vervangen alle bestaande regels.
quote_id optioneel string (uuid) De offerte waar deze factuur uit voortkomt, of null. kan leeg zijn (null)
description optioneel string Korte omschrijving; staat boven de regels. kan leeg zijn (null) · maximaal 20000 tekens
language optioneel string Taal van de factuur: nl, en, de of fr. een van: nl, en, de, fr
invoice_date optioneel string (date) Factuurdatum (JJJJ-MM-DD).
due_date optioneel string (date) Vervaldatum (JJJJ-MM-DD). Laat je hem weg, dan is het de factuurdatum plus de betaaltermijn.
payment_term_days optioneel integer Betaaltermijn in dagen. Zonder opgave de standaardtermijn van het bedrijf. van 0 tot 365
terms_conditions optioneel string Voorwaarden op de factuur. kan leeg zijn (null) · maximaal 20000 tekens
notes optioneel string Opmerkingen voor de klant op de factuur. Bij het registreren van een betaling: een notitie bij die betaling. kan leeg zijn (null) · maximaal 20000 tekens
outro_text optioneel string Slottekst onder de regels. kan leeg zijn (null) · maximaal 20000 tekens
hide_line_amounts optioneel boolean Verbergt de bedragen per regel op de factuur; de klant ziet alleen het totaal.
discount_percentage optioneel number Korting over het totaal, in procenten. van 0 tot 100
discount_amount optioneel number Korting over het totaal, als bedrag. van 0 tot 9999999
discount_description optioneel string Waarom de korting is gegeven; staat op de factuur. kan leeg zijn (null) · maximaal 500 tekens

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/invoices" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
  "title": "Veranda 400 × 300",
  "items": [
    {
      "name": "Veranda",
      "quantity": 1,
      "unit_price": "2450.00",
      "tax_rate": "21.00"
    }
  ]
}'
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'invoices', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'customer_id' => '9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70',
        'title' => 'Veranda 400 × 300',
        'items' => [
            0 => [
                'name' => 'Veranda',
                'quantity' => 1,
                'unit_price' => '2450.00',
                'tax_rate' => '21.00',
            ],
        ],
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/invoices', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
  "title": "Veranda 400 × 300",
  "items": [
    {
      "name": "Veranda",
      "quantity": 1,
      "unit_price": "2450.00",
      "tax_rate": "21.00"
    }
  ]
}),
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/invoices",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
        "title": "Veranda 400 × 300",
        "items": [
            {
                "name": "Veranda",
                "quantity": 1,
                "unit_price": "2450.00",
                "tax_rate": "21.00"
            }
        ]
    },
)
data = response.json()["data"]

Antwoord 201

Voorbeeldantwoord
{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "term_amount": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00",
        "credited_item_id": null
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Factuur bijwerken

PATCH /api/v1/invoices/{invoice}

Wijzigt alleen de velden die je meestuurt. items vervangt alle regels als geheel. Alleen een concept kan nog veranderen: is de factuur verstuurd, dan staat hij in de boekhouding van de klant en volgt er een 409.

Scope
invoices.write — Facturen aanmaken (ook van een offerte) en wijzigen (alleen concepten), annuleren, betalingen registreren, crediteren en een terugbetaling vastleggen
Vereiste functie
invoices

Stuur de ETag mee in If-Match, dan overschrijf je nooit per ongeluk een nieuwere versie.

Padparameters

NaamTypeOmschrijving
invoice verplicht string (uuid) De id (UUID) van de factuur.

Body (JSON)

VeldTypeOmschrijving
title optioneel string Titel van de factuur. Verplicht bij aanmaken. maximaal 255 tekens
description optioneel string Korte omschrijving; staat boven de regels. kan leeg zijn (null) · maximaal 20000 tekens
language optioneel string Taal van de factuur: nl, en, de of fr. een van: nl, en, de, fr
invoice_date optioneel string (date) Factuurdatum (JJJJ-MM-DD).
due_date optioneel string (date) Vervaldatum (JJJJ-MM-DD). Laat je hem weg, dan is het de factuurdatum plus de betaaltermijn.
payment_term_days optioneel integer Betaaltermijn in dagen. Zonder opgave de standaardtermijn van het bedrijf. van 0 tot 365
terms_conditions optioneel string Voorwaarden op de factuur. kan leeg zijn (null) · maximaal 20000 tekens
notes optioneel string Opmerkingen voor de klant op de factuur. Bij het registreren van een betaling: een notitie bij die betaling. kan leeg zijn (null) · maximaal 20000 tekens
outro_text optioneel string Slottekst onder de regels. kan leeg zijn (null) · maximaal 20000 tekens
hide_line_amounts optioneel boolean Verbergt de bedragen per regel op de factuur; de klant ziet alleen het totaal.
discount_percentage optioneel number Korting over het totaal, in procenten. van 0 tot 100
discount_amount optioneel number Korting over het totaal, als bedrag. van 0 tot 9999999
discount_description optioneel string Waarom de korting is gegeven; staat op de factuur. kan leeg zijn (null) · maximaal 500 tekens
items optioneel array De regels (maximaal 200). Bij invoer: een lijst met per regel name (verplicht) en optioneel type, description, sku, quantity, unit, unit_price, unit_price_incl, discount_percentage, discount_amount, discount_description, tax_rate en is_taxable. Ze vervangen alle bestaande regels.

Voorbeeldverzoek

cURL
curl -X PATCH "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "notes": "Graag betalen binnen 14 dagen."
}'
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('PATCH', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', [
    'json' => [
        'notes' => 'Graag betalen binnen 14 dagen.',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "notes": "Graag betalen binnen 14 dagen."
}),
});

const { data } = await response.json();
Python
import os

import requests

response = requests.patch(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    json={
        "notes": "Graag betalen binnen 14 dagen."
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "term_amount": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00",
        "credited_item_id": null
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Factuur versturen

POST /api/v1/invoices/{invoice}/send

Mailt de factuur naar de klant met het notificatiesjabloon van het bedrijf en zet de status op verstuurd. Opnieuw versturen telt als herinnering: reminder_count gaat omhoog. Bij een creditnota of een (deels) gecrediteerde factuur blijft de status staan; alleen sent_at wordt bijgewerkt.

Scope
invoices.send — Facturen naar klanten mailen en de betaallink voor de klant ophalen
Vereiste functie
invoices

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

NaamTypeOmschrijving
invoice verplicht string (uuid) De id (UUID) van de factuur.

Body (JSON)

VeldTypeOmschrijving
message optioneel string Persoonlijk bericht in de mail aan de klant. kan leeg zijn (null) · maximaal 5000 tekens

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/send" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "message": "Bijgaand de factuur voor de geplaatste veranda."
}'
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/send', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'message' => 'Bijgaand de factuur voor de geplaatste veranda.',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "message": "Bijgaand de factuur voor de geplaatste veranda."
}),
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/send",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "message": "Bijgaand de factuur voor de geplaatste veranda."
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "term_amount": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00",
        "credited_item_id": null
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Markeren als verstuurd (zonder mail)

POST /api/v1/invoices/{invoice}/mark-sent

Zet een concept op verstuurd zonder dat Klantly een mail naar de klant stuurt, zoals de knop in de app. Gebruik dit als je de factuur zelf hebt bezorgd: zelf gemaild, op papier of via je boekhouding. sent_at wordt gevuld en het event invoice.sent volgt. Daarna kun je er een betaling op registreren. Staat de factuur al op verstuurd of later, dan komt hij ongewijzigd terug; een geannuleerd concept geeft 409. Stuur een Idempotency-Key mee.

Scope
invoices.write — Facturen aanmaken (ook van een offerte) en wijzigen (alleen concepten), annuleren, betalingen registreren, crediteren en een terugbetaling vastleggen
Vereiste functie
invoices

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

NaamTypeOmschrijving
invoice verplicht string (uuid) De id (UUID) van de factuur.

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/mark-sent" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/mark-sent', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/mark-sent', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/mark-sent",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "term_amount": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00",
        "credited_item_id": null
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Factuur annuleren

POST /api/v1/invoices/{invoice}/cancel

Zet de factuur op geannuleerd. Een betaalde of (deels) gecrediteerde factuur kan niet worden geannuleerd (409); corrigeer een verstuurde factuur met Factuur crediteren.

Scope
invoices.write — Facturen aanmaken (ook van een offerte) en wijzigen (alleen concepten), annuleren, betalingen registreren, crediteren en een terugbetaling vastleggen
Vereiste functie
invoices

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

NaamTypeOmschrijving
invoice verplicht string (uuid) De id (UUID) van de factuur.

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/cancel" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/cancel', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "term_amount": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00",
        "credited_item_id": null
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Betaling registreren

POST /api/v1/invoices/{invoice}/payments

Legt een betaling vast die buiten Klantly binnenkwam, bijvoorbeeld een bankoverschrijving. Het bedrag kan nooit hoger zijn dan wat er nog openstaat. Is de factuur daarmee volledig voldaan, dan gaat hij op betaald en volgt het event invoice.paid.

Scope
invoices.write — Facturen aanmaken (ook van een offerte) en wijzigen (alleen concepten), annuleren, betalingen registreren, crediteren en een terugbetaling vastleggen
Vereiste functie
invoices

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

NaamTypeOmschrijving
invoice verplicht string (uuid) De id (UUID) van de factuur.

Body (JSON)

VeldTypeOmschrijving
amount verplicht number Het bedrag van de betaling die je registreert. Nooit meer dan wat er openstaat. van 0 tot 9999999
payment_method optioneel string Hoe er betaald is: bank_transfer, cash, card, ideal, credit_card, paypal, bancontact of other. een van: bank_transfer, cash, card, ideal, credit_card, paypal, bancontact, other
reference optioneel string Je eigen kenmerk bij de betaling, bijvoorbeeld het bankafschrift of de transactie-id. kan leeg zijn (null) · maximaal 255 tekens
notes optioneel string Opmerkingen voor de klant op de factuur. Bij het registreren van een betaling: een notitie bij die betaling. kan leeg zijn (null) · maximaal 1000 tekens

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/payments" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "amount": "2964.50",
  "payment_method": "bank_transfer",
  "reference": "NL02ABNA0123456789"
}'
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/payments', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'amount' => '2964.50',
        'payment_method' => 'bank_transfer',
        'reference' => 'NL02ABNA0123456789',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/payments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "amount": "2964.50",
  "payment_method": "bank_transfer",
  "reference": "NL02ABNA0123456789"
}),
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/payments",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "amount": "2964.50",
        "payment_method": "bank_transfer",
        "reference": "NL02ABNA0123456789"
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "term_amount": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00",
        "credited_item_id": null
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Factuur crediteren

POST /api/v1/invoices/{invoice}/credit

Maakt een creditnota op een verstuurde of betaalde factuur, zoals de knop in de app. mode=full crediteert alles wat nog open staat voor creditering, mode=lines per regel een aantal (lines[].item_id en lines[].quantity) en mode=amount een vrij bedrag inclusief btw tegen een btw-tarief dat op de factuur voorkomt. Het antwoord (201) is de creditnota: een invoice met type credit_note, negatieve regels en totalen en credited_invoice_id. Het deel dat met het openstaande bedrag verrekend kan worden, wordt verrekend; de rest staat als refund_amount op de creditnota en moet naar de klant terug. Meer crediteren dan er nog op de factuur staat geeft 422 op amount, lines of lines.N.quantity; een concept, geannuleerde of al volledig gecrediteerde factuur, of een creditnota, geeft 409. Daarna volgen de events invoice.created (de creditnota) en invoice.credited (de factuur). Stuur altijd een Idempotency-Key mee.

Scope
invoices.write — Facturen aanmaken (ook van een offerte) en wijzigen (alleen concepten), annuleren, betalingen registreren, crediteren en een terugbetaling vastleggen
Vereiste functie
invoices

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

NaamTypeOmschrijving
invoice verplicht string (uuid) De id (UUID) van de factuur.

Body (JSON)

VeldTypeOmschrijving
mode verplicht string Wat je crediteert: full (alles wat nog niet gecrediteerd is), lines (per regel een aantal) of amount (een vrij bedrag). een van: full, lines, amount
reason verplicht string De reden van de creditering (verplicht, maximaal 500 tekens); staat op de creditnota. maximaal 500 tekens
lines optioneel array Bij mode=lines: de regels die je crediteert, elk met item_id en quantity.
amount optioneel number Bij mode=amount: het bedrag inclusief btw dat je crediteert. Nooit meer dan er op de factuur nog te crediteren is. van 0 tot 9999999
tax_rate optioneel number Bij mode=amount: het btw-tarief van dat bedrag. Moet op de factuur voorkomen; zonder opgave het eerste tarief van de factuur. kan leeg zijn (null) · van 0 tot 100
invoice_date optioneel string (date) Datum van de creditnota (JJJJ-MM-DD); standaard vandaag.

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/credit" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "mode": "amount",
  "reason": "Korting na klacht over de montage",
  "amount": "150.00",
  "tax_rate": "21.00"
}'
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/credit', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'mode' => 'amount',
        'reason' => 'Korting na klacht over de montage',
        'amount' => '150.00',
        'tax_rate' => '21.00',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/credit', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "mode": "amount",
  "reason": "Korting na klacht over de montage",
  "amount": "150.00",
  "tax_rate": "21.00"
}),
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/credit",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "mode": "amount",
        "reason": "Korting na klacht over de montage",
        "amount": "150.00",
        "tax_rate": "21.00"
    },
)
data = response.json()["data"]

Antwoord 201

Voorbeeldantwoord
{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "term_amount": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00",
        "credited_item_id": null
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Terugbetaling vastleggen

POST /api/v1/invoices/{invoice}/refunded

Legt vast dat het terug te betalen deel van een creditnota (refund_amount) aan de klant is overgemaakt; refunded_at wordt gevuld en credit_note_state wordt refunded. Alleen op een creditnota met credit_note_state refund_pending, anders 409. Met via=mollie betaalt Klantly het bedrag echt terug via Mollie (alleen als de factuur genoeg via Mollie is betaald, anders 409); weigert Mollie, dan 422 op refund. Bij een gedeeltelijke terugbetaling blijft credit_note_state refund_pending en betaalt een nieuwe aanroep alleen de rest.

Scope
invoices.write — Facturen aanmaken (ook van een offerte) en wijzigen (alleen concepten), annuleren, betalingen registreren, crediteren en een terugbetaling vastleggen
Vereiste functie
invoices

Stuur een Idempotency-Key mee, dan maakt een nieuwe poging na een time-out geen dubbel record.

Padparameters

NaamTypeOmschrijving
invoice verplicht string (uuid) De id (UUID) van de factuur.

Body (JSON)

VeldTypeOmschrijving
via optioneel string manual (standaard): alleen vastleggen dat je zelf hebt terugbetaald. mollie: echt terugbetalen via de Mollie-betaling(en) van de oorspronkelijke factuur. een van: manual, mollie
payment_method optioneel string Hoe er is terugbetaald: bank_transfer, cash, card, ideal, credit_card, paypal, bancontact of other. een van: bank_transfer, cash, card, ideal, credit_card, paypal, bancontact, other
reference optioneel string Je eigen kenmerk bij de terugbetaling, bijvoorbeeld het bankafschrift. kan leeg zijn (null) · maximaal 255 tekens

Voorbeeldverzoek

cURL
curl -X POST "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/refunded" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "payment_method": "bank_transfer",
  "reference": "NL02ABNA0123456789"
}'
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/refunded', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'payment_method' => 'bank_transfer',
        'reference' => 'NL02ABNA0123456789',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/refunded', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "payment_method": "bank_transfer",
  "reference": "NL02ABNA0123456789"
}),
});

const { data } = await response.json();
Python
import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/refunded",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "payment_method": "bank_transfer",
        "reference": "NL02ABNA0123456789"
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "term_amount": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00",
        "credited_item_id": null
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Factuur als pdf

GET /api/v1/invoices/{invoice}/pdf

Geeft de factuur als pdf, zoals de klant hem krijgt: in de huisstijl van het bedrijf en in de taal van de factuur. Handig om hem in je boekhouding bij de boeking te bewaren. De eerste keer rendert Klantly hem; daarna komt hij uit de cache tot de factuur verandert. Valt onder de zwaardere limiet.

Scope
invoices.read — Facturen lezen, met regels, bedragen, betalingen en de klantgegevens erop
Vereiste functie
invoices

Padparameters

NaamTypeOmschrijving
invoice verplicht string (uuid) De id (UUID) van de factuur.

Voorbeeldverzoek

cURL
curl "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/pdf" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -o document.pdf
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/pdf');

file_put_contents('document.pdf', (string) $response->getBody());
JavaScript
import { writeFile } from 'node:fs/promises';

const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/pdf', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

await writeFile('document.pdf', Buffer.from(await response.arrayBuffer()));
Python
import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/pdf",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
with open("document.pdf", "wb") as pdf:
    pdf.write(response.content)

Antwoord 200

Het antwoord is het bestand zelf (application/pdf), geen JSON. Content-Disposition bevat de bestandsnaam.

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Factuur verwijderen

DELETE /api/v1/invoices/{invoice}

Verwijdert de factuur. Alleen een concept kan weg: een verstuurde factuur blijft staan.

Scope
invoices.delete — Concept-facturen verwijderen
Vereiste functie
invoices

Padparameters

NaamTypeOmschrijving
invoice verplicht string (uuid) De id (UUID) van de factuur.

Voorbeeldverzoek

cURL
curl -X DELETE "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"
PHP
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('DELETE', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70');

$data = json_decode((string) $response->getBody(), true)['data'];
JavaScript
const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();
Python
import os

import requests

response = requests.delete(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwoord 200

Voorbeeldantwoord
{
  "data": {
    "object": "note",
    "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92",
    "deleted": true
  }
}

Mogelijke fouten

Daarnaast kan elk endpoint de algemene fouten geven, zoals een ongeldige sleutel of een bereikte limiet. Bekijk alle foutcodes.

Het object

Alle velden zijn altijd aanwezig; een veld zonder waarde is null.

VeldTypeOmschrijving
object string Altijd "invoice".
id string (uuid) Unieke id (UUID).
number string Factuurnummer, bijvoorbeeld FAC-00042; geeft Klantly zelf.
type string invoice (factuur) of credit_note (creditnota). Een creditnota heeft negatieve regels en totalen. een van: invoice, credit_note
status string draft (concept), sent (verstuurd), viewed (bekeken), paid (betaald), partial (deels betaald), overdue (te laat), cancelled (geannuleerd), refunded (terugbetaald) of credited (gecrediteerd: volledig tegengeboekt, telt niet als betaald en niet als openstaand). een van: draft, sent, viewed, paid, partial, overdue, cancelled, refunded, credited
title string Titel van de factuur. Verplicht bij aanmaken. kan leeg zijn (null)
description string Korte omschrijving; staat boven de regels. kan leeg zijn (null)
customer_id string (uuid) De klant. Verplicht bij aanmaken; naam, adres en contactgegevens komen van de klant. kan leeg zijn (null)
customer object De klantgegevens op de factuur, zoals ze bij het aanmaken waren.
customer.type string individual (particulier) of business (bedrijf). kan leeg zijn (null)
customer.name string Naam; bij een bedrijf de bedrijfsnaam. kan leeg zijn (null)
customer.email string E-mailadres. kan leeg zijn (null)
customer.phone string Telefoonnummer. kan leeg zijn (null)
customer.address string Straat en huisnummer. kan leeg zijn (null)
customer.postal_code string Postcode. kan leeg zijn (null)
customer.city string Plaats. kan leeg zijn (null)
customer.country string Land. kan leeg zijn (null)
customer.company_name string Bedrijfsnaam. kan leeg zijn (null)
customer.vat_number string Btw-nummer. kan leeg zijn (null)
customer.coc_number string KvK-nummer. kan leeg zijn (null)
quote_id string (uuid) De offerte waar deze factuur uit voortkomt, of null. kan leeg zijn (null)
deal_id string (uuid) De deal op het pipelinebord waar deze factuur bij hoort, of null. kan leeg zijn (null)
language string Taal van de factuur: nl, en, de of fr. een van: nl, en, de, fr
currency string Altijd "EUR".
invoice_date string (date) Factuurdatum (JJJJ-MM-DD). kan leeg zijn (null)
due_date string (date) Vervaldatum (JJJJ-MM-DD). Laat je hem weg, dan is het de factuurdatum plus de betaaltermijn. kan leeg zijn (null)
payment_term_days integer Betaaltermijn in dagen. Zonder opgave de standaardtermijn van het bedrijf. kan leeg zijn (null)
is_term_invoice boolean Is dit een termijnfactuur (een deel van een offerte).
term_percentage string Welk deel van de offerte deze termijnfactuur beslaat, in procenten; anders null. kan leeg zijn (null)
term_amount string Vast termijnbedrag incl. btw (gelijk aan het factuurtotaal) als de termijn op een bedrag staat in plaats van een percentage; anders null. kan leeg zijn (null)
terms_conditions string Voorwaarden op de factuur. kan leeg zijn (null)
notes string Opmerkingen voor de klant op de factuur. Bij het registreren van een betaling: een notitie bij die betaling. kan leeg zijn (null)
outro_text string Slottekst onder de regels. kan leeg zijn (null)
hide_line_amounts boolean Verbergt de bedragen per regel op de factuur; de klant ziet alleen het totaal.
discount_percentage string Korting over het totaal, in procenten.
discount_amount string Korting over het totaal, als bedrag.
discount_description string Waarom de korting is gegeven; staat op de factuur. kan leeg zijn (null)
subtotal string Totaal zonder btw, als tekst met twee decimalen.
tax_amount string Btw-bedrag.
total string Totaal inclusief btw.
amount_paid string Wat er tot nu toe is betaald.
amount_due string Wat er nog openstaat. Na een creditering op een betaalde factuur is dit op 0,00 geklemd; het terug te betalen bedrag staat dan op de creditnota (refund_amount, credit_note_state).
sent_at string (date-time) Wanneer de factuur naar de klant is gestuurd. kan leeg zijn (null)
viewed_at string (date-time) Wanneer de klant hem opende. kan leeg zijn (null)
paid_at string (date-time) Wanneer de factuur volledig is voldaan. kan leeg zijn (null)
cancelled_at string (date-time) Wanneer de factuur is geannuleerd. kan leeg zijn (null)
credited_invoice_id string (uuid) Bij een creditnota: de factuur die ze tegenboekt; anders null. kan leeg zijn (null)
credited_invoice_number string Bij een creditnota: het nummer van de gecrediteerde factuur, vastgelegd bij het aanmaken; anders null. kan leeg zijn (null)
credit_reason string Bij een creditnota: de reden van de creditering; anders null. kan leeg zijn (null)
refund_amount string Bij een creditnota: het deel dat niet met het openstaande bedrag kon worden verrekend en in geld terug moet naar de klant (positief); bij een factuur null. kan leeg zijn (null)
refunded_at string (date-time) Bij een creditnota: wanneer de terugbetaling is vastgelegd; anders null. kan leeg zijn (null)
credit_note_state string Bij een creditnota: refund_pending (er moet nog geld terug), refunded (terugbetaald) of settled (volledig verrekend met de factuur); bij een factuur null. kan leeg zijn (null) · een van: refund_pending, refunded, settled
credited_amount string Bij een factuur: wat er in totaal met creditnota's is tegengeboekt, inclusief btw (positief). amount_due is totaal min betaald min gecrediteerd.
credit_note_ids array<string> Bij een factuur: de id's van haar creditnota's, oudste eerst; bij een creditnota een lege lijst.
items array<object> De regels (maximaal 200). Bij invoer: een lijst met per regel name (verplicht) en optioneel type, description, sku, quantity, unit, unit_price, unit_price_incl, discount_percentage, discount_amount, discount_description, tax_rate en is_taxable. Ze vervangen alle bestaande regels.
items.object string Altijd "invoice_item".
items.id string (uuid) Unieke id van de regel (UUID).
items.type string product, service, expense, discount of custom (een vrij bedrag op een creditnota). een van: product, service, expense, discount, custom
items.name string Naam van de regel.
items.description string Omschrijving onder de regel. kan leeg zijn (null)
items.sku string Artikelnummer. kan leeg zijn (null)
items.quantity string Aantal.
items.unit string Eenheid, bijvoorbeeld stuk of uur. kan leeg zijn (null)
items.unit_price string Prijs per eenheid, zonder btw.
items.unit_price_incl string Prijs per eenheid inclusief btw, zoals ingevoerd. Is hij gevuld, dan rekent de regel vanaf dit bedrag (unit_price en line_total zijn daarvan afgeleid) en klopt het totaal tot op de cent met de ingevoerde prijs. null = de regel rekent vanaf unit_price. kan leeg zijn (null)
items.discount_percentage string Korting op deze regel, in procenten.
items.discount_amount string Korting op deze regel, als bedrag.
items.discount_description string Waarom de korting op deze regel is gegeven. kan leeg zijn (null)
items.line_total string Regeltotaal zonder btw, na korting.
items.line_total_incl string Regeltotaal inclusief btw, na korting. Alleen gevuld als de regel vanaf unit_price_incl rekent; anders null. kan leeg zijn (null)
items.is_taxable boolean Telt deze regel mee voor de btw.
items.tax_rate string Btw-tarief van deze regel, in procenten.
items.credited_item_id string (uuid) Op een creditnota: de factuurregel die deze regel tegenboekt; null bij een vrij bedrag of op een factuur. kan leeg zijn (null)
payments array<object> De geregistreerde betalingen op deze factuur, oudste eerst.
payments.object string Altijd "invoice_payment".
payments.id string (uuid) Unieke id van de betaling.
payments.amount string Het betaalde bedrag.
payments.type string full (volledig), deposit (aanbetaling) of partial (deelbetaling). een van: full, deposit, partial
payments.status string open, pending, paid, failed, expired, cancelled of refunded. een van: open, pending, paid, failed, expired, cancelled, refunded
payments.payment_method string Hoe er is betaald, bijvoorbeeld bank_transfer of ideal. kan leeg zijn (null)
payments.description string Notitie bij de betaling. kan leeg zijn (null)
payments.paid_at string (date-time) Wanneer de betaling binnenkwam. kan leeg zijn (null)
payments.created_at string (date-time) Wanneer de betaling is vastgelegd.
created_at string (date-time) Wanneer de factuur is aangemaakt.
updated_at string (date-time) Wanneer de factuur voor het laatst is gewijzigd.