> For the complete documentation index, see [llms.txt](https://invoice4u.gitbook.io/invoice4u-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://invoice4u.gitbook.io/invoice4u-docs/documents/credit-invoices.md).

# Credit Invoices (Full & Partial)

A **credit invoice** (`DocumentType: 4`) reverses all or part of a previously issued invoice or invoice-receipt. It is created with the regular [Create a Document](/invoice4u-docs/documents/create-document.md) endpoint — what makes it special is the `Invoices` reference array and the validation rules around it.

{% hint style="info" %}
**Partial credits are the most common support issue.** The key rule: each referenced document can only be credited up to its **remaining creditable balance** — `Total − CreditAmount` (what hasn't been credited yet). Read the [validation rules](#validation-rules) before integrating.
{% endhint %}

## The three ways to issue a credit

| Mode                  | How                                                                                       | When to use                                                                                                                    |
| --------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Full credit**       | Reference the original document with `ReceiptAmount` equal to its full remaining balance. | Cancel an invoice entirely. Original becomes `FullyCredited` (StatusID 3).                                                     |
| **Partial credit**    | Reference the original with `ReceiptAmount` **less than** the remaining balance.          | Refund one item, correct an overcharge. Original becomes `PartiallyCredited` (StatusID 4); you can credit the remainder later. |
| **Standalone credit** | No `Invoices` array — just `Items` (and/or `Payments`).                                   | Credit for something not tied to a specific system document (e.g. imported/legacy invoices).                                   |

A credit invoice with **no** references, no items, and no payments is rejected with `InvoiceCreditMustHaveRefDocuments` (57).

## Request structure (referenced credit)

```http
POST /Services/ApiService.svc/CreateDocument HTTP/1.1
Host: apiqa.invoice4u.co.il
Content-Type: application/json

{
  "doc": {
    "DocumentType": 4,
    "DocumentReffType": 1,
    "ClientID": 88231,
    "Subject": "Credit for invoice 20260123",
    "TaxIncluded": true,
    "Invoices": [
      { "ID": "7f6a2c1e-1111-2222-3333-444455556666", "ReceiptAmount": 50.0 }
    ],
    "Items": [
      { "Name": "Refund - Pro plan June", "Quantity": 1, "Price": 50.0 }
    ]
  },
  "token": "<token>"
}
```

Field notes:

| Field                      | Rule                                                                                                                                |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `DocumentType`             | `4` (InvoiceCredit).                                                                                                                |
| `DocumentReffType`         | Type of the documents being credited: `1` (Invoice) or `3` (InvoiceReceipt) **only**. Anything else → `DocumentReffTypeNotInRange`. |
| `Invoices[].ID`            | GUID of the document to credit (`ID` field of the original, not `DocumentNumber`). Must belong to your organization.                |
| `Invoices[].ReceiptAmount` | The amount to credit against **that** document. Positive numbers — do **not** negate.                                               |
| `Items`                    | Item lines describing what is credited, with **positive** prices. The server handles the accounting sign.                           |
| `ClientID`                 | Must match the customer on the referenced documents.                                                                                |

You can credit **multiple documents in one credit invoice** — add one entry per document to `Invoices`, each with its own `ReceiptAmount`.

## Validation rules

Checked per row of `Invoices` (error `Paramters` contains `"Row Number - N"`):

1. **Existence & ownership** — the GUID must resolve to a document in your organization → `DocumentIDDoesntExists`.
2. **Customer match** — the referenced document's `ClientID` must equal the credit's `ClientID` → `ReceiptClientNameDoesntMatchInvoiceClientName`.
3. **Type match** — the referenced document's type must equal `DocumentReffType` → `ReceiptDocumentReffTypeDoesntMatchInvoiceDocumentType`.
4. **Status** — a document that is already `FullyCredited` (StatusID 3) cannot be credited again → `DocumentStatusInValid`.
5. **Amount ceiling** — the partial-credit rule:

$$0 < \text{ReceiptAmount} \le \text{Total} - \text{CreditAmount}$$

`CreditAmount` is the sum of all credits already applied to that document. Exceeding the remaining balance (or sending `0`/negative) → `DocumentReceiptAmountOutOfRange`.

```mermaid
flowchart TD
    classDef step fill:#E7D9FC,stroke:#9B6DD6,color:#333
    classDef dec fill:#D2F0D2,stroke:#4CAF50,color:#333
    classDef err fill:#FFD9A0,stroke:#E8A33D,color:#333
    classDef cb fill:#BBDEFB,stroke:#42A5F5,color:#333

    A[DocumentType 4]:::step --> B{Invoices refs<br/>supplied?}:::dec
    B -- ✗ --> C{Items or<br/>Payments?}:::dec
    C -- none --> E1[InvoiceCreditMustHaveRefDocuments 57]:::err
    C -- ✓ --> D[Standalone credit]:::cb
    B -- ✓ --> F{DocumentReffType<br/>1 or 3?}:::dec
    F -- ✗ --> E2[DocumentReffTypeNotInRange 53]:::err
    F -- ✓ --> G[Per referenced row]:::step
    G --> H{Exists in org?}:::dec
    H -- ✗ --> E3[DocumentIDDoesntExists 48]:::err
    H -- ✓ --> I{Customer matches?}:::dec
    I -- ✗ --> E4[ReceiptClientNameDoesntMatch<br/>InvoiceClientName 52]:::err
    I -- ✓ --> J{Type matches ReffType?}:::dec
    J -- ✗ --> E5[ReceiptDocumentReffTypeDoesntMatch<br/>InvoiceDocumentType 54]:::err
    J -- ✓ --> K{Not fully credited?}:::dec
    K -- ✗ --> E6[DocumentStatusInValid 49]:::err
    K -- ✓ --> L{"0 < ReceiptAmount ≤<br/>Total − CreditAmount"}:::dec
    L -- ✗ --> E7[DocumentReceiptAmountOutOfRange 50]:::err
    L -- ✓ --> M[Credit created]:::cb
    M --> N{Running credit<br/>== Total?}:::dec
    N -- ✓ --> O[Original → FullyCredited 3]:::step
    N -- ✗ --> P[Original → PartiallyCredited 4]:::step
```

## What happens after a successful credit

* The referenced document's `CreditAmount` increases by your `ReceiptAmount`.
* Its `StatusID` becomes `4` (PartiallyCredited) or `3` (FullyCredited) when the running credit reaches `Total`.
* The credit invoice itself gets its own legal `DocumentNumber` in the credit-invoice sequence.
* Fetch the original with [Get a Single Document](/invoice4u-docs/documents/get-document.md) to read the updated `CreditAmount`, `Balance` and `StatusID` before issuing further credits.

## Common pitfalls

| Symptom                                                 | Cause                                                         | Fix                                                                                                         |
| ------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `DocumentReceiptAmountOutOfRange` on a "valid" amount   | Earlier partial credits already consumed part of the balance. | Fetch the original first; credit at most `Total − CreditAmount`.                                            |
| `DocumentReceiptAmountOutOfRange` with negative amounts | Sending negative `ReceiptAmount`/prices to "subtract".        | Send positive values — the document type carries the sign.                                                  |
| `DocumentStatusInValid`                                 | Original is already fully credited.                           | Nothing left to credit; check `StatusID` before the call.                                                   |
| `DocumentReffTypeNotInRange`                            | Trying to credit a receipt, quote or order.                   | Only Invoice (1) and InvoiceReceipt (3) can be credited. Cancel receipts with a cancelling receipt instead. |
| Sum mismatches on multi-row credits                     | Rounding across rows.                                         | Round each `ReceiptAmount` to 2 decimals; keep items total equal to the sum of `ReceiptAmount`s.            |

## Errors

| Error (ID)                                                   | Meaning                                                          |
| ------------------------------------------------------------ | ---------------------------------------------------------------- |
| `InvoiceCreditMustHaveRefDocuments` (57)                     | No references, items or payments supplied.                       |
| `DocumentReffTypeNotInRange` (53)                            | `DocumentReffType` is not Invoice/InvoiceReceipt.                |
| `DocumentIDDoesntExists` (48)                                | Referenced GUID not found in your organization.                  |
| `ReceiptClientNameDoesntMatchInvoiceClientName` (52)         | Customer mismatch between credit and referenced document.        |
| `ReceiptDocumentReffTypeDoesntMatchInvoiceDocumentType` (54) | Referenced document's type ≠ `DocumentReffType`.                 |
| `DocumentStatusInValid` (49)                                 | Referenced document already fully credited.                      |
| `DocumentReceiptAmountOutOfRange` (50)                       | `ReceiptAmount` ≤ 0 or exceeds the remaining creditable balance. |

## Try it

## Create a document

> Creates a signed, numbered document. Totals are computed server-side from Items/Payments. Check the returned Errors list before using the result.

```json
{"openapi":"3.0.3","info":{"title":"Invoice4U API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Create and retrieve documents (invoices, receipts, etc.)."}],"servers":[{"url":"https://api.invoice4u.co.il/Services/ApiService.svc","description":"Production"},{"url":"https://apiqa.invoice4u.co.il/Services/ApiService.svc","description":"QA (staging)"}],"paths":{"/CreateDocument":{"post":{"tags":["Documents"],"operationId":"CreateDocument","summary":"Create a document","description":"Creates a signed, numbered document. Totals are computed server-side from Items/Payments. Check the returned Errors list before using the result.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["doc","token"],"properties":{"doc":{"$ref":"#/components/schemas/Document"},"token":{"type":"string"}}}}}},"responses":{"200":{"description":"The created document (or a document carrying Errors).","content":{"application/json":{"schema":{"type":"object","properties":{"CreateDocumentResult":{"$ref":"#/components/schemas/Document"}}}}}}}}}},"components":{"schemas":{"Document":{"allOf":[{"$ref":"#/components/schemas/CommonObject"},{"type":"object","required":["DocumentType"],"properties":{"ID":{"type":"string","format":"uuid","readOnly":true},"DocumentNumber":{"type":"integer","format":"int64","readOnly":true,"description":"Legal sequential number, per type."},"DocumentType":{"type":"integer","description":"1 Invoice, 2 Receipt, 3 InvoiceReceipt, 4 InvoiceCredit, 5 ProformaInvoice, 6 InvoiceOrder, 7 InvoiceQuote, 8 InvoiceShip, 9 Deposits, 10 SupplierInvoiceToInventory, 13 PurchaseOrder.","enum":[1,2,3,4,5,6,7,8,9,10,13]},"Subject":{"type":"string","nullable":true},"ClientID":{"type":"integer","nullable":true,"description":"Existing customer ID. Required unless GeneralCustomer is supplied or the type doesn't need a customer."},"GeneralCustomer":{"$ref":"#/components/schemas/GenerelCustomer"},"Items":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/DocumentItem"}},"Payments":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/Payment"}},"Invoices":{"type":"array","nullable":true,"description":"Referenced documents (each with ID and ReceiptAmount). Requires DocumentReffType.","items":{"type":"object","properties":{"ID":{"type":"string","format":"uuid"},"ReceiptAmount":{"type":"number","format":"double"}}}},"DocumentReffType":{"type":"integer","description":"Type of the referenced documents."},"IssueDate":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to today. Not in the future; not before your latest document of the type."},"Currency":{"type":"string","nullable":true},"ConversionRate":{"type":"number","format":"double","description":"Auto-resolved when 0."},"TaxPercentage":{"type":"number","format":"double","nullable":true},"TaxIncluded":{"type":"boolean","description":"Whether item prices include VAT."},"Discount":{"$ref":"#/components/schemas/Discount"},"BranchID":{"type":"integer","nullable":true,"description":"Defaults to the organization's default branch."},"Language":{"type":"integer","description":"1 Hebrew, 2 English."},"AssociatedEmails":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/AssociatedEmail"}},"ExternalComments":{"type":"string","nullable":true,"maxLength":5000},"InternalComments":{"type":"string","nullable":true},"EmailCustomComment":{"type":"string","nullable":true},"ApiIdentifier":{"type":"string","nullable":true,"description":"Idempotency key. Auto-generated if missing."},"ApiDuplicityTimeValidation":{"type":"integer","description":"Duplicate-detection window in seconds. Default 60."},"PaymentDueDate":{"type":"string","format":"date-time","nullable":true},"Deduction":{"type":"number","format":"double","description":"Withholding-tax deduction (receipts)."},"CloseReceipt":{"type":"boolean"},"IsSelfInvoice":{"type":"boolean"},"SupplierId":{"type":"integer","nullable":true},"SupplierName":{"type":"string","nullable":true},"UseDecimalValues":{"type":"boolean"},"AutoFixPaymentsMismatchItems":{"type":"boolean","description":"Auto-fix ±0.01 rounding gaps between payments and items."},"AutoFixMismatchItemName":{"type":"string","nullable":true},"Total":{"type":"number","format":"double","readOnly":true},"TotalWithoutTax":{"type":"number","format":"double","readOnly":true},"TotalTaxAmount":{"type":"number","format":"double","readOnly":true},"StatusID":{"type":"integer","readOnly":true,"description":"1 Open, 2 Closed, 3 FullyCredited, 4 PartiallyCredited, 5 Cancelled."},"PrintOriginalPDFLink":{"type":"string","readOnly":true},"PrintCertifiedCopyPDFLink":{"type":"string","readOnly":true},"CipherText":{"type":"string","readOnly":true},"CipherTextOriginal":{"type":"string","readOnly":true},"AllocationNumber":{"type":"string","nullable":true,"readOnly":true},"Paid":{"type":"number","format":"double","readOnly":true},"CreditAmount":{"type":"number","format":"double","readOnly":true},"Balance":{"type":"number","format":"double","readOnly":true}}}]},"CommonObject":{"type":"object","description":"Response envelope inherited by most objects. Server-generated — never send these fields in requests. Always check Errors before using the payload.","properties":{"Errors":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/CommonError"}},"Info":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/CommonInfo"}},"OpenInfo":{"type":"object","readOnly":true,"additionalProperties":{"type":"string"},"nullable":true}}},"CommonError":{"type":"object","properties":{"ID":{"type":"integer","description":"Numeric error code, e.g. 80 = UnauthorizedUser, 134 = DocumentAlreadyCreated."},"Error":{"type":"string","description":"Error name."},"Paramters":{"type":"string","nullable":true,"description":"Optional context, e.g. \"Row Number - 0\"."}}},"CommonInfo":{"type":"object","properties":{"ID":{"type":"integer"},"Info":{"type":"string"},"Paramters":{"type":"string","nullable":true}}},"GenerelCustomer":{"type":"object","required":["Name"],"description":"One-off (general) customer for documents without a stored customer record.","properties":{"ID":{"type":"integer"},"Name":{"type":"string"},"Identifier":{"type":"string","description":"VAT/ID number."}}},"DocumentItem":{"type":"object","required":["Name","Quantity","Price"],"properties":{"Name":{"type":"string"},"Description":{"type":"string","nullable":true},"Price":{"type":"number","format":"double","description":"Unit price."},"PriceIncludeTax":{"type":"number","format":"double","description":"Price including VAT (when TaxIncluded)."},"Quantity":{"type":"number","format":"double"},"TaxPercentage":{"type":"number","format":"double","nullable":true,"description":"Per-item VAT override."},"Discount":{"$ref":"#/components/schemas/Discount"},"Code":{"type":"string","nullable":true,"description":"Catalog code."},"LawyerIdentifier":{"type":"string","nullable":true,"description":"Lawyer accounts: \"1\" deposits, \"2\" expenses."},"InventoryId":{"type":"integer","nullable":true},"WarehouseId":{"type":"integer","nullable":true},"Total":{"type":"number","format":"double","readOnly":true},"TotalWithoutTax":{"type":"number","format":"double","readOnly":true},"TotalTax":{"type":"number","format":"double","readOnly":true}}},"Discount":{"type":"object","required":["Value"],"properties":{"Value":{"type":"number","format":"double"},"IsNominal":{"type":"boolean","description":"true = fixed amount, false = percent."},"BeforeTax":{"type":"boolean"}}},"Payment":{"type":"object","required":["PaymentType","Amount"],"properties":{"ID":{"type":"integer","description":"Existing payment ID — used for Deposits documents."},"PaymentType":{"type":"integer","description":"1 CreditCard, 2 Check, 3 MoneyTransfer, 4 Cash, 5 Credit, 6 WithholdingTax, 7 Other, 8 Bit, 9 PayBox.","enum":[1,2,3,4,5,6,7,8,9]},"Amount":{"type":"number","format":"double"},"Date":{"type":"string","format":"date-time","nullable":true},"DateStr":{"type":"string","nullable":true,"description":"Alternative string date when Date is not set."},"NumberOfPayments":{"type":"integer","description":"Credit-card installments."},"CreditCardName":{"type":"string","nullable":true,"description":"Card brand name; resolved against configured credit companies."},"CreditCardType":{"type":"integer","nullable":true},"PaymentNumber":{"type":"string","nullable":true,"description":"Check number / last 4 card digits."},"BankName":{"type":"string","nullable":true},"BranchName":{"type":"string","nullable":true},"AccountNumber":{"type":"string","nullable":true},"PayerID":{"type":"string","nullable":true},"ExpirationDate":{"type":"string","nullable":true},"PaymentTypeOtherId":{"type":"integer","description":"Sub-type when PaymentType=7 (Other)."},"PaymentTypeLiteral":{"type":"string","nullable":true}}},"AssociatedEmail":{"type":"object","required":["Mail"],"properties":{"Mail":{"type":"string","format":"email"},"IsUserMail":{"type":"boolean","description":"true marks the copy sent to the account owner."},"ClientId":{"type":"integer","nullable":true},"IsSendDoc":{"type":"boolean","nullable":true}}}}}}
```