---
title: "Create a credit note draft"
method: POST
path: "/v1/invoices/{invoiceId}/credit-note"
tags: ["Invoices"]
---

# Create a credit note draft

`POST /v1/invoices/{invoiceId}/credit-note`

## Request

- Base URL: `https://api.frihet.io`
- URL: `https://api.frihet.io/v1/invoices/{invoiceId}/credit-note`
- Auth: API key in header `X-API-Key`

Create a rectificative invoice (credit note) as a **draft**, by differences
(`TipoRectificativa = I`), for the full amount of an existing invoice.

The endpoint never issues. The draft carries no fiscal number, no hash and
no VeriFactu submission: those happen when a person issues it in the app.
A previous version created the document with `sent` status — that behaviour
is gone.

Requirements:
  * Plan `pro` or above. Otherwise `403 PLAN_UPGRADE_REQUIRED`.
  * An `Idempotency-Key` header. Otherwise `400 IDEMPOTENCY_KEY_REQUIRED`.
  * The original invoice must not be `draft`, `cancelled`, or already
    fully credited.

Errors carry a stable machine-readable `code` alongside `error`.

## Path parameters

- `invoiceId` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `reason` 'refund' | 'discount' | 'error' | 'cancellation' | 'other', required: Reason for the credit note. Maps to the R-type (R1 for `error`, R4 otherwise).
  - `reasonDescription` string: Optional free-text description of the reason
  - `fullCredit` boolean: Only `true` (or omitted) is supported: a full credit by differences. Sending `false` returns `400 PARTIAL_CREDIT_NOT_IMPLEMENTED` — partial corrections need the corrected lines, which this endpoint does not accept. Create those in the app.
  - `issueDate` string, date: Issue date for the credit note. Defaults to today.

## Response `201`

Credit note draft created — and the status a REPLAY returns too. A retry
with the same Idempotency-Key receives this same `201`, the same `id` and
the same body, plus `X-Idempotent-Replayed: true`; no second document is
written. (Earlier versions replayed as `200`.)

- CreditNoteResult: Result of `POST /v1/invoices/{invoiceId}/credit-note`. `status` is always `draft` — the endpoint creates, it does not issue.
  - `data` object
    - `success` boolean
    - `creditNote` object
      - `id` string: ID of the newly created credit note draft
      - `documentNumber` string: Provisional reference, not a fiscal number. Numbering happens on issue.
      - `originalInvoiceId` string
      - `reason` string
      - `fullCredit` boolean
      - `status` 'draft': Always `draft`.
      - `rectificationMethod` 'I': Always `I` (por diferencias). `S` is not offered over the API.
      - `totalCredited` number: Tax-inclusive amount credited, as a positive number.
      - `replayed` boolean: DEPRECATED and no longer emitted. A replay is now signalled by the `X-Idempotent-Replayed: true` response header, and the replayed body is byte-identical to the original — which a body-level flag would contradict. Documented only so existing clients know the field is absent rather than false.

## Other responses

- `400`: Validation error, or one of `IDEMPOTENCY_KEY_REQUIRED`, `PARTIAL_CREDIT_NOT_IMPLEMENTED`, `ORIGINAL_INVOICE_IS_DRAFT`, `ORIGINAL_INVOICE_IS_CANCELLED`, `ORIGINAL_INVOICE_FULLY_CREDITED`, `ORIGINAL_INVOICE_MISSING_FISCAL_ZONE` (the original invoice has no `clientLocation`, so the correct rectificativa form cannot be determined).
- `401`: Authentication required or invalid API key
- `403`: The effective plan is below `pro` (`PLAN_UPGRADE_REQUIRED`).
- `404`: Resource not found
- `409`: Either `IDEMPOTENCY_KEY_REUSED` — the key is live for a DIFFERENT operation (another endpoint, or this one with a different body), which is refused without executing — or `IDEMPOTENCY_REQUEST_IN_PROGRESS`: a request with this key is still running, or its outcome could not be recorded. Reconcile the invoice's credit notes before starting another operation; a fresh key would create a second document.
- `429`: Rate limit exceeded (100 requests per minute)
- `500`: Internal server error

---

[API](https://skmtc.dev/frihet/apis/frihet-api.md) · [All operations](https://skmtc.dev/frihet/apis/frihet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/frihet/apis/frihet-api/revisions/3dd37f6a72d1?raw)