💳Credit Note (Avoir)

Learn how to generate and dispatch credit notes through Docs-Dispatcher with complete end-to-end examples in 4 languages (curl, Node.js, PHP, Java).

Overview

This comprehensive recipe walks you through the complete credit note generation and dispatch workflow:

1. Authenticate and set up Basic Authentication

2. Prepare your credit note data with original invoice reference

3. Validate the request (recommended safety check)

4. Send the credit note to your accounting provider

5. Handle the response and track status

By the end of this guide, you'll have working code to automatically generate and send credit notes (refunds, corrections, cancellations) to providers like Qonto, PennyLane, iPaidThat.

What You'll Learn

• How to structure credit note requests for different providers

• Reference original invoices correctly

• Handle negative amounts and corrections

• Best practices for validation before sending

• Error handling strategies

• Provider-specific credit note requirements

• Complete working examples in 4 languages

Prerequisites

Before you begin:

• Docs-Dispatcher account with email and password

• At least one invoicing provider configured (Qonto, PennyLane, iPaidThat, or SuperPDP)

• Template created in Templater (or use API to create one)

• Original invoice ID/reference (the invoice you're crediting)

• Basic understanding of REST APIs

No provider configured yet? You can still test with the validation endpoint - it checks your request format without calling external APIs or charging credits.

What is a Credit Note?

A credit note (avoir in French) is a document that:

• Cancels all or part of an invoice

• Refunds amounts already paid

• Corrects errors in original invoices

• Adjusts prices or quantities

• Credits customer accounts

Common scenarios:

• Product returned by customer

• Service not delivered as agreed

• Pricing error on original invoice

• Quantity correction

• Discount applied retroactively

• Invoice cancellation

Step 1: Authentication

Dispatcher API uses HTTP Basic Authentication. You'll need your Dispatcher account email and password for all API calls.

Setup Credentials

# Store credentials as environment variables
export EMAIL="[email protected]"
export PASSWORD="your-password"

No token management needed! Unlike JWT-based APIs, Basic Auth doesn't require separate authentication endpoints or token refresh. Your credentials are sent with each request.

Quick links:

• Full authentication guide

• Using Basic Auth with Dispatcher

Step 2: Prepare Credit Note Data

Structure your credit note data according to the CompositeRequest model. Credit notes require special fields to reference the original invoice.

Basic Credit Note Structure

{
  "providerName": "qonto",
  "documentType": "CREDIT",
  "template": {
    "id": 124,
    "data": {
      "creditNoteNumber": "CN-2026-001",
      "date": "2026-02-13",
      "originalInvoice": {
        "number": "INV-2026-001",
        "id": "qonto_inv_789",
        "date": "2026-01-15",
        "total": 2400.00
      },
      "customer": {
        "name": "Acme Corp",
        "email": "[email protected]",
        "address": "123 Main St",
        "city": "Paris",
        "postalCode": "75001",
        "country": "FR"
      },
      "reason": "Product returned",
      "items": [
        {
          "description": "Logo Design (returned)",
          "quantity": 1,
          "unitPrice": 500.00,
          "total": 500.00
        }
      ],
      "subtotal": 500.00,
      "taxRate": 0.20,
      "taxAmount": 100.00,
      "total": 600.00
    }
  },
  "invoicing": {
    "originalInvoiceId": "qonto_inv_789",
    "creditReason": "PRODUCT_RETURN"
  },
  "metadata": {
    "orderId": "ORD-2026-12345",
    "customerId": "CUST-789",
    "returnId": "RET-2026-045"
  }
}

Required Fields

Field	Type	Description
providerName	string	Provider to use: qonto, pennylane, ipaidthat, superpdp
documentType	string	Must be CREDIT for credit notes
template.id	number	Template ID from Templater (use credit note template)
template.data	object	Template variables (schema depends on template)
invoicing.originalInvoiceId	string	Provider's invoice ID being credited

Credit Note Specific Fields

Field	Type	Description
template.data.originalInvoice	object	Original invoice reference details
template.data.originalInvoice.number	string	Original invoice number
template.data.originalInvoice.id	string	Provider's invoice ID
template.data.reason	string	Reason for credit note
invoicing.creditReason	string	Structured reason code (see below)

Credit Reason Codes

Code	Description	When to Use
PRODUCT_RETURN	Product returned by customer	Physical goods returned
SERVICE_NOT_DELIVERED	Service not provided	Service cancelled or incomplete
PRICING_ERROR	Error in original pricing	Wrong price charged
QUANTITY_ERROR	Quantity correction needed	Wrong quantity invoiced
DISCOUNT_APPLIED	Retroactive discount	Price adjustment after invoice
INVOICE_CANCELLATION	Full invoice cancellation	Complete cancellation
OTHER	Other reason	Custom scenarios

Partial vs Full Credit

Partial Credit (some items/amounts):

{
  "template": {
    "data": {
      "items": [
        {
          "description": "Logo Design (returned)",
          "quantity": 1,
          "unitPrice": 500.00,
          "total": 500.00
        }
      ],
      "subtotal": 500.00,
      "total": 600.00
    }
  }
}

Full Credit (entire invoice):

{
  "template": {
    "data": {
      "items": [
        {
          "description": "Web Development Services",
          "quantity": 10,
          "unitPrice": 150.00,
          "total": 1500.00
        },
        {
          "description": "Logo Design",
          "quantity": 1,
          "unitPrice": 500.00,
          "total": 500.00
        }
      ],
      "subtotal": 2000.00,
      "total": 2400.00
    }
  }
}

Amounts in Credit Notes: Most providers expect positive amounts in credit notes (not negative). The document type CREDIT indicates these amounts should be subtracted from customer balance. Check your provider's specific requirements.

Step 3: Validate Request (Recommended)

Before sending real credit notes, validate your request structure. This checks for errors without calling external providers or charging credits.

Why Validate?

• Catch errors early (before external API calls)

• Verify original invoice reference is correct

• Free and fast (< 100ms response)

• No risk of duplicate credit notes

• Test during development

Validation Request

curl -X POST https://api.docs-dispatcher.io/api/invoicing/validate \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "qonto",
    "documentType": "CREDIT",
    "template": {
      "id": 124,
      "data": {
        "creditNoteNumber": "CN-2026-001",
        "date": "2026-02-13",
        "originalInvoice": {
          "number": "INV-2026-001",
          "id": "qonto_inv_789"
        },
        "customer": {
          "name": "Acme Corp",
          "email": "[email protected]"
        },
        "reason": "Product returned",
        "items": [
          {
            "description": "Logo Design (returned)",
            "quantity": 1,
            "unitPrice": 500.00,
            "total": 500.00
          }
        ],
        "total": 600.00
      }
    },
    "invoicing": {
      "originalInvoiceId": "qonto_inv_789",
      "creditReason": "PRODUCT_RETURN"
    }
  }'

Validation Success Response

{
  "valid": true,
  "message": "Credit note request is valid and ready for dispatch",
  "warnings": [
    {
      "field": "template.data.total",
      "message": "Credit amount (600.00) is 25% of original invoice (2400.00)",
      "level": "info"
    }
  ]
}

Validation Error Response

{
  "valid": false,
  "errors": [
    {
      "field": "invoicing.originalInvoiceId",
      "message": "Original invoice ID is required for credit notes",
      "value": null
    },
    {
      "field": "template.data.total",
      "message": "Credit total (2500.00) exceeds original invoice total (2400.00)",
      "expected": "max 2400.00",
      "actual": 2500.00
    }
  ]
}

Validation passed? You're ready to send the real credit note! Simply change /validate to /invoicing in the endpoint URL.

More on validation:

• Validation guide

• Validate then Send recipe

Step 4: Send Credit Note (Real Dispatch)

Once validation passes, send the actual credit note by changing the endpoint from /validate to /invoicing.

Sync Mode (Default)

Synchronous mode waits for the provider to complete the operation and returns the full response immediately.

curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "qonto",
    "documentType": "CREDIT",
    "template": {
      "id": 124,
      "data": {
        "creditNoteNumber": "CN-2026-001",
        "date": "2026-02-13",
        "originalInvoice": {
          "number": "INV-2026-001",
          "id": "qonto_inv_789",
          "date": "2026-01-15",
          "total": 2400.00
        },
        "customer": {
          "name": "Acme Corp",
          "email": "[email protected]",
          "address": "123 Main St",
          "city": "Paris",
          "postalCode": "75001",
          "country": "FR"
        },
        "reason": "Product returned - Logo Design",
        "items": [
          {
            "description": "Logo Design (returned)",
            "quantity": 1,
            "unitPrice": 500.00,
            "total": 500.00
          }
        ],
        "subtotal": 500.00,
        "taxRate": 0.20,
        "taxAmount": 100.00,
        "total": 600.00
      }
    },
    "invoicing": {
      "originalInvoiceId": "qonto_inv_789",
      "creditReason": "PRODUCT_RETURN"
    },
    "metadata": {
      "orderId": "ORD-2026-12345",
      "customerId": "CUST-789",
      "returnId": "RET-2026-045"
    }
  }'

Success Response:

{
  "success": true,
  "dispatchId": "disp_credit_xyz123abc",
  "providerResponse": {
    "creditNoteId": "qonto_credit_456",
    "creditNoteNumber": "CN-2026-001",
    "status": "issued",
    "url": "https://qonto.com/credit-notes/456",
    "originalInvoiceId": "qonto_inv_789",
    "creditedAmount": 600.00,
    "createdAt": "2026-02-13T12:30:00Z"
  },
  "generatedDocument": {
    "url": "https://storage.docs-dispatcher.io/credit-notes/CN-2026-001.pdf",
    "size": 189456,
    "contentType": "application/pdf",
    "expiresAt": "2026-03-13T12:30:00Z"
  },
  "metadata": {
    "orderId": "ORD-2026-12345",
    "customerId": "CUST-789",
    "returnId": "RET-2026-045"
  },
  "executionTime": 2.1
}

When to use sync mode:

• User is waiting for result (interactive workflows)

• Quick operations (expected completion < 30 seconds)

• Simple error handling (errors returned immediately)

• Testing and development

Async Mode (Recommended for Production)

Asynchronous mode queues the request immediately and processes it in the background. You receive a webhook notification when complete.

curl -X POST https://api.docs-dispatcher.io/api/invoicing?async=true \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "qonto",
    "documentType": "CREDIT",
    "template": {
      "id": 124,
      "data": {
        "creditNoteNumber": "CN-2026-001",
        "originalInvoice": {...},
        "customer": {...},
        "items": [...],
        "total": 600.00
      }
    },
    "invoicing": {
      "originalInvoiceId": "qonto_inv_789",
      "creditReason": "PRODUCT_RETURN"
    },
  }'

Immediate Response:

{
  "success": true,
  "dispatchId": "disp_async_credit_def789",
  "status": "queued",
  "queuedAt": "2026-02-13T12:30:00Z",
  "estimatedCompletionTime": "2026-02-13T12:32:00Z"
}

{
  "event": "dispatch_completed",
  "dispatchId": "disp_async_credit_def789",
  "service": "invoicing",
  "documentType": "CREDIT",
  "status": "success",
  "timestamp": "2026-02-13T12:31:45Z",
  "data": {
    "providerResponse": {
      "creditNoteId": "qonto_credit_456",
      "status": "issued",
      "url": "https://qonto.com/credit-notes/456",
      "originalInvoiceId": "qonto_inv_789",
      "creditedAmount": 600.00
    },
    "generatedDocument": {
      "url": "https://storage.docs-dispatcher.io/credit-notes/CN-2026-001.pdf",
      "size": 189456
    }
  },
  "metadata": {
    "returnId": "RET-2026-045"
  }
}

More on execution modes:

• Sync vs Async guide

• Async Flow recipe

• Webhook events

Step 5: Handle Response

Process the dispatch response and handle errors gracefully.

Success Response Fields

Field	Description
success	true if dispatch succeeded
dispatchId	Unique dispatch identifier (use for tracking)
providerResponse.creditNoteId	Provider's credit note ID
providerResponse.originalInvoiceId	Original invoice reference
providerResponse.creditedAmount	Amount credited to customer
generatedDocument	Generated PDF document URL and metadata
metadata	Your custom tracking data (echoed back)

Error Response

{
  "success": false,
  "error": "provider_error",
  "message": "Credit note creation failed: Original invoice not found",
  "dispatchId": "disp_failed_credit_xyz",
  "providerError": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice with ID qonto_inv_999 does not exist",
    "details": {
      "invoiceId": "qonto_inv_999"
    }
  }
}

Common Error Types

Error Type	Cause	Solution
validation_error	Invalid request format	Check required fields
invoice_not_found	Original invoice doesn't exist	Verify invoice ID
invoice_already_credited	Invoice already has credit note	Check existing credits
credit_exceeds_invoice	Credit amount > invoice amount	Reduce credit amount
authentication_error	Invalid/expired JWT	Refresh token
provider_error	Provider API error	Check provider error details

Complete Examples

Here are complete, runnable examples in 4 languages showing the full credit note workflow from authentication to dispatch.

curl (Complete Flow)

#!/bin/bash

# Step 1: Authenticate
echo "Step 1: Getting Basic Auth credentials..."
AUTH_RESPONSE=$(curl -s -X POST https://api.docs-dispatcher.io/auth \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password"
  }')

JWT_TOKEN=$(echo $AUTH_RESPONSE | jq -r '.token')
echo "JWT Token: ${JWT_TOKEN:0:20}..."

# Step 2: Prepare credit note data
CREDIT_REQUEST='{
  "providerName": "qonto",
  "documentType": "CREDIT",
  "template": {
    "id": 124,
    "data": {
      "creditNoteNumber": "CN-2026-001",
      "date": "2026-02-13",
      "originalInvoice": {
        "number": "INV-2026-001",
        "id": "qonto_inv_789",
        "date": "2026-01-15",
        "total": 2400.00
      },
      "customer": {
        "name": "Acme Corp",
        "email": "[email protected]",
        "address": "123 Main St",
        "city": "Paris",
        "postalCode": "75001",
        "country": "FR"
      },
      "reason": "Product returned - Logo Design",
      "items": [
        {
          "description": "Logo Design (returned)",
          "quantity": 1,
          "unitPrice": 500.00,
          "total": 500.00
        }
      ],
      "subtotal": 500.00,
      "taxRate": 0.20,
      "taxAmount": 100.00,
      "total": 600.00
    }
  },
  "invoicing": {
    "originalInvoiceId": "qonto_inv_789",
    "creditReason": "PRODUCT_RETURN"
  },
  "metadata": {
    "returnId": "RET-2026-045",
    "customerId": "CUST-789"
  }
}'

# Step 3: Validate request
echo "Step 2: Validating credit note request..."
VALIDATION_RESPONSE=$(curl -s -X POST https://api.docs-dispatcher.io/api/invoicing/validate \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d "$CREDIT_REQUEST")

VALID=$(echo $VALIDATION_RESPONSE | jq -r '.valid')
if [ "$VALID" = "true" ]; then
  echo "Validation passed!"
else
  echo "Validation failed:"
  echo $VALIDATION_RESPONSE | jq '.errors'
  exit 1
fi

# Step 4: Send credit note
echo "Step 3: Sending credit note..."
DISPATCH_RESPONSE=$(curl -s -X POST https://api.docs-dispatcher.io/api/invoicing \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d "$CREDIT_REQUEST")

# Step 5: Handle response
SUCCESS=$(echo $DISPATCH_RESPONSE | jq -r '.success')
if [ "$SUCCESS" = "true" ]; then
  echo "Credit note sent successfully!"
  echo "Dispatch ID: $(echo $DISPATCH_RESPONSE | jq -r '.dispatchId')"
  echo "Credit Note ID: $(echo $DISPATCH_RESPONSE | jq -r '.providerResponse.creditNoteId')"
  echo "Original Invoice: $(echo $DISPATCH_RESPONSE | jq -r '.providerResponse.originalInvoiceId')"
  echo "Credited Amount: $(echo $DISPATCH_RESPONSE | jq -r '.providerResponse.creditedAmount')"
  echo "Credit Note URL: $(echo $DISPATCH_RESPONSE | jq -r '.providerResponse.url')"
  echo "Document URL: $(echo $DISPATCH_RESPONSE | jq -r '.generatedDocument.url')"
else
  echo "Credit note dispatch failed:"
  echo $DISPATCH_RESPONSE | jq
  exit 1
fi

Node.js (Complete Flow)

const fetch = require('node-fetch');

// Configuration
const CONFIG = {
  templaterApiUrl: 'https://api.docs-dispatcher.io',
  dispatcherApiUrl: 'https://api.docs-dispatcher.io',
  email: '[email protected]',
  password: 'your-secure-password'
};

// Step 1: Authentication
async function authenticate() {
  console.log('Step 1: Getting Basic Auth credentials...');

  const response = await fetch(`${CONFIG.templaterApiUrl}/auth`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: CONFIG.email,
      password: CONFIG.password
    })
  });

  if (!response.ok) {
    throw new Error(`Authentication failed: ${response.statusText}`);
  }

  const data = await response.json();
  console.log(`JWT Token obtained (expires: ${data.expiresAt})`);

  return data.token;
}

// Step 2: Prepare credit note data
function prepareCreditNoteData() {
  return {
    providerName: 'qonto',
    documentType: 'CREDIT',
    template: {
      id: 124,
      data: {
        creditNoteNumber: 'CN-2026-001',
        date: '2026-02-13',
        originalInvoice: {
          number: 'INV-2026-001',
          id: 'qonto_inv_789',
          date: '2026-01-15',
          total: 2400.00
        },
        customer: {
          name: 'Acme Corp',
          email: '[email protected]',
          address: '123 Main St',
          city: 'Paris',
          postalCode: '75001',
          country: 'FR'
        },
        reason: 'Product returned - Logo Design',
        items: [
          {
            description: 'Logo Design (returned)',
            quantity: 1,
            unitPrice: 500.00,
            total: 500.00
          }
        ],
        subtotal: 500.00,
        taxRate: 0.20,
        taxAmount: 100.00,
        total: 600.00
      }
    },
    invoicing: {
      originalInvoiceId: 'qonto_inv_789',
      creditReason: 'PRODUCT_RETURN'
    },
    metadata: {
      returnId: 'RET-2026-045',
      customerId: 'CUST-789'
    }
  };
}

// Step 3: Validate request
async function validateCreditNote(jwtToken, creditData) {
  console.log('Step 2: Validating credit note request...');

  const response = await fetch(
    `${CONFIG.dispatcherApiUrl}/api/invoicing/validate`,
    {
      method: 'POST',
      headers: {
        'Authorization': authHeader,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(creditData)
    }
  );

  const validation = await response.json();

  if (!validation.valid) {
    console.error('Validation failed:');
    validation.errors.forEach(err => {
      console.error(`  - ${err.field}: ${err.message}`);
    });
    throw new Error('Validation failed');
  }

  console.log('Validation passed!');

  if (validation.warnings && validation.warnings.length > 0) {
    console.warn('Warnings:');
    validation.warnings.forEach(warn => {
      console.warn(`  - ${warn.field}: ${warn.message}`);
    });
  }

  return validation;
}

// Step 4: Send credit note
async function sendCreditNote(jwtToken, creditData) {
  console.log('Step 3: Sending credit note...');

  const response = await fetch(
    `${CONFIG.dispatcherApiUrl}/api/invoicing`,
    {
      method: 'POST',
      headers: {
        'Authorization': authHeader,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(creditData)
    }
  );

  const result = await response.json();

  if (!result.success) {
    throw new Error(
      `Credit note dispatch failed: ${result.message}\n` +
      `Provider error: ${JSON.stringify(result.providerError)}`
    );
  }

  console.log('Credit note sent successfully!');
  return result;
}

// Step 5: Handle response
function handleResponse(result) {
  console.log('\n=== Credit Note Dispatch Result ===');
  console.log(`Dispatch ID: ${result.dispatchId}`);
  console.log(`Credit Note ID: ${result.providerResponse.creditNoteId}`);
  console.log(`Status: ${result.providerResponse.status}`);
  console.log(`Original Invoice: ${result.providerResponse.originalInvoiceId}`);
  console.log(`Credited Amount: ${result.providerResponse.creditedAmount}`);
  console.log(`Credit Note URL: ${result.providerResponse.url}`);
  console.log(`Document URL: ${result.generatedDocument.url}`);
  console.log(`Document Size: ${result.generatedDocument.size} bytes`);
  console.log(`Execution Time: ${result.executionTime}s`);

  if (result.metadata) {
    console.log('\nMetadata:');
    Object.entries(result.metadata).forEach(([key, value]) => {
      console.log(`  ${key}: ${value}`);
    });
  }
}

// Main execution flow
async function main() {
  try {
    // Step 1: Authenticate
    const email = process.env.DOCS_DISPATCHER_EMAIL;
const password = process.env.DOCS_DISPATCHER_PASSWORD;
const authHeader = createBasicAuthHeader(email, password);
// await authenticate();

    // Step 2: Prepare data
    const creditData = prepareCreditNoteData();

    // Step 3: Validate
    await validateCreditNote(jwtToken, creditData);

    // Step 4: Send credit note
    const result = await sendCreditNote(jwtToken, creditData);

    // Step 5: Handle response
    handleResponse(result);

  } catch (error) {
    console.error('Error:', error.message);
    process.exit(1);
  }
}

// Run
main();

PHP (Complete Flow)

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

// Configuration
class Config {
    const TEMPLATER_API_URL = 'https://api.docs-dispatcher.io';
    const DISPATCHER_API_URL = 'https://api.docs-dispatcher.io';
    const EMAIL = '[email protected]';
    const PASSWORD = 'your-secure-password';
}

class CreditNoteDispatcher {
    private $client;
    private $jwtToken;

    public function __construct() {
        $this->client = new Client();
    }

    // Step 1: Authentication
    public function authenticate() {
        echo "Step 1: Getting Basic Auth credentials...\n";

        try {
            $response = $this->client->post(Config::TEMPLATER_API_URL . '/auth', [
                'json' => [
                    'email' => Config::EMAIL,
                    'password' => Config::PASSWORD
                ]
            ]);

            $data = json_decode($response->getBody(), true);
            $this->jwtToken = $data['token'];

            echo "JWT Token obtained (expires: {$data['expiresAt']})\n";

            return $this->jwtToken;

        } catch (RequestException $e) {
            throw new Exception("Authentication failed: " . $e->getMessage());
        }
    }

    // Step 2: Prepare credit note data
    public function prepareCreditNoteData() {
        return [
            'providerName' => 'qonto',
            'documentType' => 'CREDIT',
            'template' => [
                'id' => 124,
                'data' => [
                    'creditNoteNumber' => 'CN-2026-001',
                    'date' => '2026-02-13',
                    'originalInvoice' => [
                        'number' => 'INV-2026-001',
                        'id' => 'qonto_inv_789',
                        'date' => '2026-01-15',
                        'total' => 2400.00
                    ],
                    'customer' => [
                        'name' => 'Acme Corp',
                        'email' => '[email protected]',
                        'address' => '123 Main St',
                        'city' => 'Paris',
                        'postalCode' => '75001',
                        'country' => 'FR'
                    ],
                    'reason' => 'Product returned - Logo Design',
                    'items' => [
                        [
                            'description' => 'Logo Design (returned)',
                            'quantity' => 1,
                            'unitPrice' => 500.00,
                            'total' => 500.00
                        ]
                    ],
                    'subtotal' => 500.00,
                    'taxRate' => 0.20,
                    'taxAmount' => 100.00,
                    'total' => 600.00
                ]
            ],
            'invoicing' => [
                'originalInvoiceId' => 'qonto_inv_789',
                'creditReason' => 'PRODUCT_RETURN'
            ],
            'metadata' => [
                'returnId' => 'RET-2026-045',
                'customerId' => 'CUST-789'
            ]
        ];
    }

    // Step 3: Validate request
    public function validateCreditNote($creditData) {
        echo "Step 2: Validating credit note request...\n";

        try {
            $response = $this->client->post(
                Config::DISPATCHER_API_URL . '/api/invoicing/validate',
                [
                    'headers' => [
                        'Authorization' => 'Bearer ' . $this->jwtToken,
                        'Content-Type' => 'application/json'
                    ],
                    'json' => $creditData
                ]
            );

            $validation = json_decode($response->getBody(), true);

            if (!$validation['valid']) {
                echo "Validation failed:\n";
                foreach ($validation['errors'] as $error) {
                    echo "  - {$error['field']}: {$error['message']}\n";
                }
                throw new Exception('Validation failed');
            }

            echo "Validation passed!\n";

            if (isset($validation['warnings']) && count($validation['warnings']) > 0) {
                echo "Warnings:\n";
                foreach ($validation['warnings'] as $warning) {
                    echo "  - {$warning['field']}: {$warning['message']}\n";
                }
            }

            return $validation;

        } catch (RequestException $e) {
            throw new Exception("Validation request failed: " . $e->getMessage());
        }
    }

    // Step 4: Send credit note
    public function sendCreditNote($creditData) {
        echo "Step 3: Sending credit note...\n";

        try {
            $response = $this->client->post(
                Config::DISPATCHER_API_URL . '/api/invoicing',
                [
                    'headers' => [
                        'Authorization' => 'Bearer ' . $this->jwtToken,
                        'Content-Type' => 'application/json'
                    ],
                    'json' => $creditData
                ]
            );

            $result = json_decode($response->getBody(), true);

            if (!$result['success']) {
                throw new Exception(
                    "Credit note dispatch failed: {$result['message']}\n" .
                    "Provider error: " . json_encode($result['providerError'])
                );
            }

            echo "Credit note sent successfully!\n";
            return $result;

        } catch (RequestException $e) {
            throw new Exception("Credit note dispatch failed: " . $e->getMessage());
        }
    }

    // Step 5: Handle response
    public function handleResponse($result) {
        echo "\n=== Credit Note Dispatch Result ===\n";
        echo "Dispatch ID: {$result['dispatchId']}\n";
        echo "Credit Note ID: {$result['providerResponse']['creditNoteId']}\n";
        echo "Status: {$result['providerResponse']['status']}\n";
        echo "Original Invoice: {$result['providerResponse']['originalInvoiceId']}\n";
        echo "Credited Amount: {$result['providerResponse']['creditedAmount']}\n";
        echo "Credit Note URL: {$result['providerResponse']['url']}\n";
        echo "Document URL: {$result['generatedDocument']['url']}\n";
        echo "Document Size: {$result['generatedDocument']['size']} bytes\n";
        echo "Execution Time: {$result['executionTime']}s\n";

        if (isset($result['metadata'])) {
            echo "\nMetadata:\n";
            foreach ($result['metadata'] as $key => $value) {
                echo "  $key: $value\n";
            }
        }
    }

    // Main execution
    public function run() {
        try {
            // Step 1: Authenticate
            $this->authenticate();

            // Step 2: Prepare data
            $creditData = $this->prepareCreditNoteData();

            // Step 3: Validate
            $this->validateCreditNote($creditData);

            // Step 4: Send credit note
            $result = $this->sendCreditNote($creditData);

            // Step 5: Handle response
            $this->handleResponse($result);

        } catch (Exception $e) {
            echo "Error: " . $e->getMessage() . "\n";
            exit(1);
        }
    }
}

// Run
$dispatcher = new CreditNoteDispatcher();
$dispatcher->run();

Java (Complete Flow)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import java.util.Map;
import java.util.HashMap;
import java.util.List;
import java.util.ArrayList;

public class CreditNoteDispatcher {

    // Configuration
    private static final String TEMPLATER_API_URL = "https://api.docs-dispatcher.io";
    private static final String DISPATCHER_API_URL = "https://api.docs-dispatcher.io";
    private static final String EMAIL = "[email protected]";
    private static final String PASSWORD = "your-secure-password";

    private final HttpClient client;
    private final Gson gson;
    private String jwtToken;

    public CreditNoteDispatcher() {
        this.client = HttpClient.newHttpClient();
        this.gson = new Gson();
    }

    // Step 1: Authentication
    public String authenticate() throws Exception {
        System.out.println("Step 1: Getting Basic Auth credentials...");

        Map<String, String> authData = new HashMap<>();
        authData.put("email", EMAIL);
        authData.put("password", PASSWORD);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(TEMPLATER_API_URL + "/auth"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(gson.toJson(authData)))
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        if (response.statusCode() != 200) {
            throw new Exception("Authentication failed: " + response.body());
        }

        JsonObject data = gson.fromJson(response.body(), JsonObject.class);
        this.jwtToken = data.get("token").getAsString();

        System.out.println("JWT Token obtained (expires: " +
            data.get("expiresAt").getAsString() + ")");

        return this.jwtToken;
    }

    // Step 2: Prepare credit note data
    public Map<String, Object> prepareCreditNoteData() {
        Map<String, Object> credit = new HashMap<>();

        credit.put("providerName", "qonto");
        credit.put("documentType", "CREDIT");

        // Template
        Map<String, Object> template = new HashMap<>();
        template.put("id", 124);

        // Template data
        Map<String, Object> templateData = new HashMap<>();
        templateData.put("creditNoteNumber", "CN-2026-001");
        templateData.put("date", "2026-02-13");
        templateData.put("reason", "Product returned - Logo Design");

        // Original invoice
        Map<String, Object> originalInvoice = new HashMap<>();
        originalInvoice.put("number", "INV-2026-001");
        originalInvoice.put("id", "qonto_inv_789");
        originalInvoice.put("date", "2026-01-15");
        originalInvoice.put("total", 2400.00);
        templateData.put("originalInvoice", originalInvoice);

        // Customer
        Map<String, String> customer = new HashMap<>();
        customer.put("name", "Acme Corp");
        customer.put("email", "[email protected]");
        customer.put("address", "123 Main St");
        customer.put("city", "Paris");
        customer.put("postalCode", "75001");
        customer.put("country", "FR");
        templateData.put("customer", customer);

        // Items
        List<Map<String, Object>> items = new ArrayList<>();
        Map<String, Object> item1 = new HashMap<>();
        item1.put("description", "Logo Design (returned)");
        item1.put("quantity", 1);
        item1.put("unitPrice", 500.00);
        item1.put("total", 500.00);
        items.add(item1);

        templateData.put("items", items);
        templateData.put("subtotal", 500.00);
        templateData.put("taxRate", 0.20);
        templateData.put("taxAmount", 100.00);
        templateData.put("total", 600.00);

        template.put("data", templateData);
        credit.put("template", template);

        // Invoicing options
        Map<String, String> invoicing = new HashMap<>();
        invoicing.put("originalInvoiceId", "qonto_inv_789");
        invoicing.put("creditReason", "PRODUCT_RETURN");
        credit.put("invoicing", invoicing);

        // Metadata
        Map<String, String> metadata = new HashMap<>();
        metadata.put("returnId", "RET-2026-045");
        metadata.put("customerId", "CUST-789");
        credit.put("metadata", metadata);

        return credit;
    }

    // Step 3: Validate request
    public JsonObject validateCreditNote(Map<String, Object> creditData) throws Exception {
        System.out.println("Step 2: Validating credit note request...");

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(DISPATCHER_API_URL + "/api/invoicing/validate"))
            .header("Authorization", "Bearer " + this.jwtToken)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(gson.toJson(creditData)))
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        JsonObject validation = gson.fromJson(response.body(), JsonObject.class);

        if (!validation.get("valid").getAsBoolean()) {
            System.err.println("Validation failed:");
            validation.getAsJsonArray("errors").forEach(error -> {
                JsonObject err = error.getAsJsonObject();
                System.err.println("  - " + err.get("field").getAsString() +
                    ": " + err.get("message").getAsString());
            });
            throw new Exception("Validation failed");
        }

        System.out.println("Validation passed!");

        if (validation.has("warnings") &&
            validation.getAsJsonArray("warnings").size() > 0) {
            System.out.println("Warnings:");
            validation.getAsJsonArray("warnings").forEach(warning -> {
                JsonObject warn = warning.getAsJsonObject();
                System.out.println("  - " + warn.get("field").getAsString() +
                    ": " + warn.get("message").getAsString());
            });
        }

        return validation;
    }

    // Step 4: Send credit note
    public JsonObject sendCreditNote(Map<String, Object> creditData) throws Exception {
        System.out.println("Step 3: Sending credit note...");

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(DISPATCHER_API_URL + "/api/invoicing"))
            .header("Authorization", "Bearer " + this.jwtToken)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(gson.toJson(creditData)))
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        JsonObject result = gson.fromJson(response.body(), JsonObject.class);

        if (!result.get("success").getAsBoolean()) {
            throw new Exception(
                "Credit note dispatch failed: " + result.get("message").getAsString() + "\n" +
                "Provider error: " + result.get("providerError").toString()
            );
        }

        System.out.println("Credit note sent successfully!");
        return result;
    }

    // Step 5: Handle response
    public void handleResponse(JsonObject result) {
        System.out.println("\n=== Credit Note Dispatch Result ===");
        System.out.println("Dispatch ID: " + result.get("dispatchId").getAsString());

        JsonObject providerResponse = result.getAsJsonObject("providerResponse");
        System.out.println("Credit Note ID: " + providerResponse.get("creditNoteId").getAsString());
        System.out.println("Status: " + providerResponse.get("status").getAsString());
        System.out.println("Original Invoice: " + providerResponse.get("originalInvoiceId").getAsString());
        System.out.println("Credited Amount: " + providerResponse.get("creditedAmount").getAsDouble());
        System.out.println("Credit Note URL: " + providerResponse.get("url").getAsString());

        JsonObject generatedDocument = result.getAsJsonObject("generatedDocument");
        System.out.println("Document URL: " + generatedDocument.get("url").getAsString());
        System.out.println("Document Size: " + generatedDocument.get("size").getAsInt() + " bytes");

        System.out.println("Execution Time: " + result.get("executionTime").getAsDouble() + "s");

        if (result.has("metadata")) {
            System.out.println("\nMetadata:");
            JsonObject metadata = result.getAsJsonObject("metadata");
            metadata.entrySet().forEach(entry -> {
                System.out.println("  " + entry.getKey() + ": " + entry.getValue().getAsString());
            });
        }
    }

    // Main execution
    public void run() {
        try {
            // Step 1: Authenticate
            authenticate();

            // Step 2: Prepare data
            Map<String, Object> creditData = prepareCreditNoteData();

            // Step 3: Validate
            validateCreditNote(creditData);

            // Step 4: Send credit note
            JsonObject result = sendCreditNote(creditData);

            // Step 5: Handle response
            handleResponse(result);

        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            System.exit(1);
        }
    }

    // Entry point
    public static void main(String[] args) {
        CreditNoteDispatcher dispatcher = new CreditNoteDispatcher();
        dispatcher.run();
    }
}

Provider-Specific Notes

Different invoicing providers have unique credit note features and requirements.

Qonto

Provider name: qonto

Credit Note Features:

• Full and partial credit notes supported

• Automatic linking to original invoice

• Customer notification optional

• Sandbox mode available for testing

Specific requirements:

• Original invoice ID required (Qonto's invoice ID)

• Credit note number must be unique

• Cannot exceed original invoice amount

• Customer email required if sending notification

Example:

{
  "providerName": "qonto",
  "documentType": "CREDIT",
  "template": {
    "id": 124,
    "data": {
      "creditNoteNumber": "CN-2026-001",
      "originalInvoice": {
        "id": "qonto_inv_789"
      }
    }
  },
  "invoicing": {
    "originalInvoiceId": "qonto_inv_789",
    "creditReason": "PRODUCT_RETURN"
  }
}

PennyLane

Provider name: pennylane

Credit Note Features:

• Comprehensive credit note support

• Automatic Chorus Pro submission for e-invoices

• Detailed reason tracking

• Multiple credit notes per invoice

Specific requirements:

• Product codes required for credited items

• Detailed reason documentation

• SIRET required for French B2B credits

• Tax breakdown must match original

Example:

{
  "providerName": "pennylane",
  "documentType": "CREDIT",
  "template": {
    "data": {
      "originalInvoice": {
        "number": "INV-2026-001",
        "id": "pennylane_inv_123"
      },
      "items": [
        {
          "description": "Logo Design (returned)",
          "productCode": "LOGO",
          "vatRate": 0.20
        }
      ]
    }
  },
  "invoicing": {
    "originalInvoiceId": "pennylane_inv_123",
    "creditReason": "PRODUCT_RETURN"
  }
}

iPaidThat

Provider name: ipaidthat

Credit Note Features:

• Standard credit note support

• Invoice reference tracking

• Customer balance adjustment

Specific requirements:

• Original invoice number required

• Credit note must not exceed original amount

• Customer email required

SuperPDP

Provider name: superpdp

Credit Note Features:

• E-invoice compliant credit notes

• Automatic archiving

• Legal documentation trail

Specific requirements:

• Complete original invoice reference

• Detailed justification required

• SIRET/SIREN for French companies

Provider Comparison

Feature	iPaidThat	Qonto	PennyLane	SuperPDP
Credit Notes	✅	✅	✅	✅
Partial Credits	✅	✅	✅	✅
Multiple Credits	✅	✅	✅	⚠️ Limited
E-Invoice Credits	❌	✅	✅	✅
Sandbox	✅	✅	✅	✅
Reason Tracking	✅	✅	✅	✅
Auto-linking	✅	✅	✅	✅

Error Handling

Common Credit Note Errors

1. Original Invoice Not Found

Cause: Invoice ID doesn't exist in provider

{
  "success": false,
  "error": "invoice_not_found",
  "message": "Original invoice qonto_inv_999 not found",
  "providerError": {
    "code": "INVOICE_NOT_FOUND",
    "invoiceId": "qonto_inv_999"
  }
}

Solution:

• Verify invoice ID is correct

• Check invoice exists in provider

• Ensure invoice belongs to same company

2. Credit Exceeds Invoice Amount

Cause: Credit total > original invoice total

{
  "success": false,
  "error": "credit_exceeds_invoice",
  "message": "Credit amount (3000.00) exceeds invoice amount (2400.00)",
  "details": {
    "creditAmount": 3000.00,
    "invoiceAmount": 2400.00,
    "maxCreditAllowed": 2400.00
  }
}

Solution:

• Reduce credit amount

• Check calculation

• Verify original invoice amount

3. Invoice Already Fully Credited

Cause: Invoice has already been fully credited

{
  "success": false,
  "error": "invoice_already_credited",
  "message": "Invoice has already been fully credited",
  "details": {
    "invoiceAmount": 2400.00,
    "existingCredits": 2400.00,
    "remainingAmount": 0.00
  }
}

Solution:

• Check existing credit notes

• Calculate remaining crediteable amount

• Adjust credit amount accordingly

Troubleshooting Common Issues

Issue 1: "Missing original invoice reference"

Symptoms:

• Validation error on originalInvoiceId

• Provider rejects credit note

Solutions:

1. Include invoicing.originalInvoiceId in request

2. Use provider's invoice ID (not your internal ID)

3. Verify invoice exists before crediting

Issue 2: "Credit amount calculation mismatch"

Symptoms:

• Provider rejects due to amount inconsistency

• Tax calculation errors

Solutions:

1. Ensure amounts are positive (not negative)

2. Match tax rates from original invoice

3. Use same rounding rules as invoice

Issue 3: "Duplicate credit note number"

Symptoms:

• Provider error about existing credit note

• Unique constraint violation

Solutions:

1. Use unique credit note numbers

2. Check existing credit notes first

3. Implement retry with new number

Next Steps

Now that you know how to generate and send credit notes:

Related Recipes

• Invoice - Generate and send invoices

• Quote - Create quotes before invoicing

• Validate then Send - Production-ready validation pattern

• Async Flow - Scale with webhooks

Core Concepts

• Request Model - Understand CompositeRequest structure

• Providers & Configurations - Configure providers

• Services - Explore all services

Provider Documentation

• Qonto - Qonto credit note features

• PennyLane - PennyLane integration details

• iPaidThat - iPaidThat configuration

• SuperPDP - SuperPDP e-invoicing

Summary

You've learned how to:

• ✅ Authenticate and obtain Basic Auth credentials

• ✅ Structure credit note requests with original invoice references

• ✅ Handle partial and full credits correctly

• ✅ Validate requests before sending

• ✅ Send credit notes in sync and async modes

• ✅ Handle responses and errors gracefully

• ✅ Implement complete workflows in 4 languages

• ✅ Troubleshoot common credit note issues

Ready for production? Follow this checklist:

1. Configure your provider credentials

2. Create credit note templates in Templater

3. Validate all requests before dispatch

4. Implement error handling for invoice references

5. Track existing credits to prevent over-crediting

6. Use async mode for scalability

7. Monitor credit note success rates

Happy crediting!