Skip to main content

Credit Notes Guide

Document Type: Credit Note
Document Type ID: 7 (verify with /document-type)

Overview​

Credit Notes are documents that:

  • ↩️ Reverse sales (full or partial)
  • 📈 AFFECT stock (inbound/return)
  • 💸 Generate credit in favor of customer
  • 🧾 Official fiscal document
  • ✅ Correct or cancel invoices

When to Use​

  • ✅ Product returns
  • ✅ Invoice error correction
  • ✅ Sale cancellation
  • ✅ Post-sale discount

Credit Note Characteristics​

CharacteristicValueDescription
Affects Stock✅ YesStock inbound
Requires Refund⚠️ DependsMay generate credit
Can be Closed✅ YesMandatory finalization
Fiscal Validation✅ YesOfficial fiscal document
Allows Editing⚠️ LimitedOnly before closing
Invoice Reference⚠️ RecommendedShould reference invoice

Types of Credit Notes​

1. Full Return​

Customer returns entire purchase.

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}
{
  "serieId": 3,
  "documentTypeId": 7,
  "entityKeyId": "CLI001",
  "entityDescription": "Example Client, Ltd",
  "obs": "Full return - defective product",
  "docReference": "INV A/123",      // Original invoice
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Product 1",
      "quantity": -2.0,            // NEGATIVE quantity
      "retailPrice": 50.00,        // Original price
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": -1,             // Stock INBOUND
      "stockBehavior": 1,
      "destinationWarehouse": 1,
      "secondTaxId": 0
    }
  ]
}
Negative Quantity

Use negative quantity (-2.0) and stockFlow = -1 for stock inbound.

2. Partial Return​

Customer returns only part of the purchase.

{
  "serieId": 3,
  "documentTypeId": 7,
  "entityKeyId": "CLI001",
  "obs": "Partial return - 1 of 2 units",
  "docReference": "INV A/123",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": -1.0,            // Only 1 unit
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": -1,
      "stockBehavior": 1,
      "destinationWarehouse": 1,
      "secondTaxId": 0
    }
  ]
}

3. Value Correction​

Correct price error without physical return.

{
  "serieId": 3,
  "documentTypeId": 7,
  "entityKeyId": "CLI001",
  "obs": "Price correction - billing error",
  "docReference": "INV A/123",
  "documentBodies": [
    {
      "itemKeyId": "PYMT001",      // Generic correction item
      "itemDescription": "Value correction",
      "quantity": -1.0,
      "retailPrice": 10.00,        // Value difference
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 0,              // Does NOT affect stock
      "stockBehavior": 0,
      "secondTaxId": 0
    }
  ]
}

4. Full Cancellation​

Cancel invoice completely (without physical return).

{
  "serieId": 3,
  "documentTypeId": 7,
  "entityKeyId": "CLI001",
  "obs": "Cancellation of invoice INV A/123 - issued by mistake",
  "docReference": "INV A/123",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": -2.0,
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": -1,             // Stock inbound
      "stockBehavior": 1,
      "destinationWarehouse": 1,
      "secondTaxId": 0
    }
  ]
}

Refund Management​

Scenario 1: Immediate Refund​

  1. Create credit note
  2. Issue negative receipt (if applicable)
  3. Record treasury outflow

Scenario 2: Credit for Future Purchases​

  1. Create credit note
  2. Record credit in accounting system
  3. Customer uses credit on next purchase

Scenario 3: Discount on Future Invoice​

  1. Create credit note
  2. Next invoice: include credit as discount

Important Validations​

Required Data​

  • ✅ documentTypeId = 7 - Credit Note
  • ✅ docReference - Reference to original invoice
  • ✅ Negative quantity - Value to credit
  • ✅ stockFlow = -1 - Stock inbound (if physical return)

Business Validations​

  • ✅ CN value ≤ Original invoice value
  • ✅ Returned quantity ≤ Sold quantity
  • ✅ Original invoice exists and is closed
  • ✅ Customer is the same as original invoice

Best Practices​

✅ Recommended​

  • Always reference original invoice in docReference
  • Include detailed reason in obs field
  • Validate values before issuing
  • Close credit note immediately
  • Photograph returned products (physical return)
  • Coordinate with finance department

❌ Avoid​

  • Issuing CN without linked invoice
  • Values higher than original invoice
  • Forgetting to register stock inbound
  • Leaving CN open
  • CN for trivial reasons (discount → use discounted invoice)

Practical Scenarios​

Return Due to Defect​

Situation: Defective product, customer wants full refund.

Steps:

  1. Verify original invoice
  2. Create CN with physical return (stockFlow = -1)
  3. Process refund
  4. Send defective product to supplier/quality

Billing Error​

Situation: Wrong price on invoice.

Steps:

  1. Create CN with value correction
  2. Don't affect stock (stockFlow = 0)
  3. Issue new correct invoice (if needed)

Post-Sale Commercial Discount​

Situation: Customer negotiated discount after invoice.

Steps:

  1. Create CN with discount value
  2. Don't affect stock
  3. Register in accounts receivable

Differences vs Invoices​

AspectInvoiceCredit Note
QuantityPositiveNegative
StockOutboundInbound
RevenueIncreasesDecreases
PurposeSaleCorrection/Return
ReferenceOptionalRequired

Invoice Integration​

Complete Flow​

graph LR
    A[Invoice Issued] --> B{Problem?}
    B -->|Yes| C[Create Credit Note]
    C --> D[Process Return]
    D --> E[Refund/Credit]
    B -->|No| F[End]

Reports and Analysis​

Important Metrics​

  • Return rate by product
  • Total CN value per period
  • Most common return reasons
  • Customers with most returns

Query CNs​

GET /api/v1/invoices?documentTypeId=7&fromDate=2025-01-01&toDate=2025-12-31
Authorization: Bearer {token}

Next Steps​

Last Updated: December 2, 2025