Table of Contents

  1. Introduction

  2. Understanding Credit Notes in Dolibarr

  3. Why Automate Refunds via REST API?

  4. API Prerequisites and Authentication

  5. Overview of Dolibarr's REST API

  6. Credit Note Structure in the API

  7. Step-by-Step Guide: Processing a Refund via API

  8. Handling Partial vs Full Refunds

  9. Use Cases and Automation Scenarios

  10. Security Considerations

  11. Common Pitfalls and Debugging Tips

  12. Extending Functionality with Custom Endpoints

  13. Best Practices for API-Based Financial Operations

  14. Conclusion

1. Introduction

Dolibarr ERP/CRM is a modular and open-source software suite used by thousands of small and medium-sized enterprises to manage their daily operations. Among its key financial features is the handling of credit notes (also called "avoir" in French), which are used to issue refunds or cancel invoices.

With the rise of automation, integrating the REST API to manage these credit note refunds programmatically becomes essential. This article provides a comprehensive guide on how to configure, implement, and use Dolibarr's REST API to issue refunds linked to credit notes.

2. Understanding Credit Notes in Dolibarr

Credit notes are accounting documents that reverse or correct issued invoices. They are typically used:

  • When a customer returns goods.

  • When an invoice contains errors.

  • To apply a discount or correction post-invoice.

In Dolibarr, credit notes are linked to original invoices. They reduce the total owed and can be converted into refunds either manually or automatically.

3. Why Automate Refunds via REST API?

Manual refund processing can be time-consuming, error-prone, and inconsistent. Automating this process via the REST API offers:

  • Speed: Instantly issue refunds when certain conditions are met.

  • Accuracy: Avoid human errors in refund calculations.

  • Scalability: Handle large volumes of transactions programmatically.

  • Integration: Sync with other platforms like eCommerce, CRM, or banking systems.

4. API Prerequisites and Authentication

Before using the REST API, ensure that:

  • The REST API module is enabled in Dolibarr (from the admin interface).

  • You have generated an API key or token for an authorized user.

  • HTTPS is enabled for secure communication.

Authentication is typically done via HTTP headers:

GET /api/index.php/invoices/ HTTP/1.1
DOLAPIKEY: your_api_key_here
Host: dolibarr.example.com

5. Overview of Dolibarr's REST API

Dolibarr provides RESTful endpoints for most major entities, including:

  • Third parties (/thirdparties)

  • Invoices (/invoices)

  • Credit notes (/suppliercreditnotes, /invoices with negative totals)

  • Payments (/payments, /paymentinvoices)

To handle refunds linked to credit notes, you generally interact with:

  • /invoices for the original invoice

  • /invoices or /suppliercreditnotes for the credit note

  • /paymentinvoices for registering refunds

6. Credit Note Structure in the API

A credit note is similar to an invoice but with a negative total. Here's an example payload:

{
  "socid": 5,
  "type": 2, // Indicates credit note
  "date": "2024-12-01",
  "lines": [
    {
      "desc": "Refunded Product",
      "subprice": -100,
      "qty": 1
    }
  ]
}

Key notes:

  • type: 2 indicates a credit note.

  • Amounts are negative.

  • Must be linked to the correct client (socid).

7. Step-by-Step Guide: Processing a Refund via API

Step 1: Retrieve Original Invoice

Use the endpoint:

GET /api/index.php/invoices/{id}

Step 2: Create the Credit Note

POST to:

POST /api/index.php/invoices

with a payload similar to the example in section 6.

Step 3: Validate the Credit Note

POST /api/index.php/invoices/{id}/validate

Step 4: Register the Refund

POST /api/index.php/paymentinvoices

Example payload:

{
  "datepaye": "2024-12-02",
  "amounts": {
    "CREDIT_NOTE_ID": 100
  },
  "accountid": 1,
  "paymenttype": 2,
  "ref": "Refund via API"
}

8. Handling Partial vs Full Refunds

When creating credit notes, you can adjust the quantity or amount of items. For partial refunds:

  • Use positive qty but adjust subprice to reflect partial amounts.

  • Ensure the total matches the intended refund.

Example for a 50% refund:

{
  "lines": [
    {
      "desc": "Partial refund",
      "subprice": -50,
      "qty": 1
    }
  ]
}

9. Use Cases and Automation Scenarios

  • E-Commerce Returns: Automatically issue credit notes and refunds when a return is processed online.

  • Billing Corrections: Create and issue refunds when overbilling is detected.

  • Subscription Management: Prorated refunds for cancelled subscriptions.

All of these can be triggered using webhook listeners or cron jobs polling for specific triggers.

10. Security Considerations

When automating financial operations:

  • Always use HTTPS.

  • Restrict API keys to specific roles.

  • Log all refund transactions.

  • Monitor API usage with rate limits.

Additionally, validate all refund requests internally before invoking API calls.

11. Common Pitfalls and Debugging Tips

  • Invalid invoice type: Ensure you set type: 2 for credit notes.

  • Wrong socid: The client ID must match.

  • Rounding issues: Double-check totals to avoid floating point errors.

  • Validation failure: Credit notes must be validated before payment.

Use Dolibarr's API logs and webserver logs to trace failed calls.

12. Extending Functionality with Custom Endpoints

Advanced users may:

  • Create modules that wrap refund logic.

  • Expose custom endpoints to consolidate multiple API steps.

  • Integrate refund workflows with external platforms (e.g. Stripe, PayPal).

This may require overriding Dolibarr's core or using the api_extra hook.

13. Best Practices for API-Based Financial Operations

  • Implement transaction logs.

  • Reconcile refunds with bank accounts regularly.

  • Use sandbox/test environments before production deployment.

  • Inform clients via automated emails when a refund is issued.

14. Conclusion

Dolibarr's REST API makes it possible to fully automate the management of credit note refunds, streamlining operations, improving accuracy, and reducing administrative overhead. With careful configuration, secure implementation, and clear business rules, companies can leverage the API to offer a faster and more professional experience for their clients while maintaining full control over their financial workflows.

Whether you're handling high-volume e-commerce transactions or occasional client reimbursements, this API integration is a powerful asset in your Dolibarr toolkit.