Credit invoice

POST

/v1/invoices/{id}/credit-notes

Creates and books a credit note for a booked invoice, by default for all that is outstanding, and lowers the invoice's outstanding balance. Each call is your own approval of the invoice: Numina does not review it, so make sure a person at your company has checked it or has approved the rules your system books by. Booking is final and cannot be undone through this API. It does not send the credit note; use POST /v1/invoices/{id}/send with the credit note's ID.

Not available to Fuld Service customers (403 booking_not_available).

Every successful call books a credit note, so send an Idempotency-Key header to retry safely. Two credit notes for the same invoice at once: one gets 409 and nothing is booked for it.

Returns 409 for a draft, an offer or a credit note, and when nothing is outstanding. Returns 400 validation_error for an amount above what is outstanding or a date in a closed accounting year.

Requires one ofinvoices:book write:ledger

Path parameters

idstring (uuid)Required
Invoice ID

Headers

Idempotency-Keystring· max 255 chars
Unique key for this request (max 255 characters). Retrying with the same key and body returns the original response instead of doing the work again.

Body

application/json

datestring· YYYY-MM-DD
Credit note date in YYYY-MM-DD format (default: today). It must be in an open accounting year.
amountnumber· ≥ 0
Amount to credit incl. VAT, in the invoice's currency (default: all that is outstanding). It cannot exceed what is outstanding. Lines are credited in proportion.
memostring· max 2000 chars
Note on the credit note (default: the invoice's note)

Errors

400Invalid input or validation failed
401Invalid or missing authentication
403Missing scope, the company is archived, or the company is on Fuld Service
404The resource does not exist in this company
409The invoice cannot be credited, has nothing outstanding, or is being updated
422The Idempotency-Key was already used with a different request
429Rate limit exceeded
500Internal Server Error

Every error has the same shape. See Errors.

cURL

curl -X POST https://api.numina.app/v1/invoices/550e8400-e29b-41d4-a716-446655440000/credit-notes \
  -H "Authorization: Bearer numi_YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-11-10",
    "amount": 1250,
    "memo": "string"
  }'

JavaScript

const response = await fetch("https://api.numina.app/v1/invoices/550e8400-e29b-41d4-a716-446655440000/credit-notes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUMINA_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "date": "2026-11-10",
    "amount": 1250,
    "memo": "string"
  }),
});

const data = await response.json();

Python

import uuid
import os

import requests

response = requests.post(
    "https://api.numina.app/v1/invoices/550e8400-e29b-41d4-a716-446655440000/credit-notes",
    headers={
        "Authorization": f"Bearer {os.environ['NUMINA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "date": "2026-11-10",
        "amount": 1250,
        "memo": "string"
    },
)
data = response.json()

Response

201

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "invoice_number": 1001,
  "type": "invoice",
  "credited_invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "sent",
  "issue_date": "2026-01-15",
  "due_date": "2026-02-15",
  "contact_id": "550e8400-e29b-41d4-a716-446655440001",
  "contact_name": "Acme ApS",
  "currency": "DKK",
  "subtotal": 10000,
  "vat": 2500,
  "vat_rate": 25,
  "total": 12500,
  "has_mixed_vat": false,
  "outstanding_balance": 12500,
  "outstanding_balance_currency": "DKK",
  "currency_rate": 0,
  "delivery_status": "sent",
  "email_delivery_status": "string",
  "email_sent_at": "string",
  "e_invoice_sent_at": "string",
  "is_overdue": false,
  "payment_state": "open",
  "unmatched_payments_note": "string",
  "items": [
    {
      "unit": "string",
      "vat_account_id": "string",
      "vat_code": "string",
      "sales_account_number": 0,
      "vat_rate": 0,
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "description": "Consulting services",
      "quantity": 10,
      "unit_price": 1000
    }
  ],
  "memo": "Project Q1 delivery",
  "payment_details": {
    "bank_name": "Danske Bank",
    "scheme": "dk-registration-number",
    "clearing_code": "3409",
    "account_number": "0012345678",
    "iban": "DK5030000012345678",
    "swift_bic": "DABADKKK"
  },
  "created_at": "2026-01-15T10:30:00Z"
}