Credit Notes API

Manage credit notes for an organization — create, list, retrieve, update, and delete.

Authentication

All endpoints require a valid Bearer token in the Authorization header.

Endpoints

Method	Path	Description
POST	/api/credit/:orgId/create	Create a new credit note
GET	/api/credit/:orgId/list	List all credit notes
GET	/api/credit/:orgId/by-code/:code	Get credit note by code
GET	/api/credit/:orgId/:creditNoteId	Get credit note by ID
PUT	/api/credit/:orgId/:creditNoteId/update	Update a credit note
DELETE	/api/credit/:orgId/:creditNoteId/delete	Delete a credit note

Path Parameters

Parameter	Type	Description
orgId	string	Organization ID
creditNoteId	string	Credit note document ID
code	string	Unique credit note code (e.g. CN-001)

---

Create Credit Note

POST /api/credit/:orgId/create

Request Body

{
  "creditNoteNumber": "CN-001",
  "date": "2026-02-20",
  "customerId": "64f1b2c3d4e5f6a7b8c9d0e1",
  "items": [
    {
      "description": "Room refund — Deluxe Suite",
      "quantity": 1,
      "rate": 5000,
      "taxId": "64f1b2c3d4e5f6a7b8c9d0e2",
      "amount": 5000
    }
  ],
  "notes": "Refund for early checkout",
  "reason": "Early checkout adjustment"
}

Success Response 201

{
  "success": true,
  "message": "Credit note created successfully",
  "data": {
    "_id": "64f1b2c3d4e5f6a7b8c9d0e3",
    "creditNoteNumber": "CN-001",
    "date": "2026-02-20",
    "customerId": "64f1b2c3d4e5f6a7b8c9d0e1",
    "items": [
      {
        "description": "Room refund — Deluxe Suite",
        "quantity": 1,
        "rate": 5000,
        "taxId": "64f1b2c3d4e5f6a7b8c9d0e2",
        "amount": 5000
      }
    ],
    "total": 5000,
    "notes": "Refund for early checkout",
    "reason": "Early checkout adjustment",
    "orgId": "64f1b2c3d4e5f6a7b8c9d0e0",
    "createdAt": "2026-02-20T10:00:00.000Z",
    "updatedAt": "2026-02-20T10:00:00.000Z"
  }
}

Error Response 400

{
  "success": false,
  "message": "Validation error",
  "errors": [
    "creditNoteNumber is required",
    "items must contain at least one entry"
  ]
}

---

List Credit Notes

GET /api/credit/:orgId/list

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	10	Results per page
search	string	—	Search by credit note number or customer name
from	string	—	Start date filter (YYYY-MM-DD)
to	string	—	End date filter (YYYY-MM-DD)

Success Response 200

{
  "success": true,
  "data": [
    {
      "_id": "64f1b2c3d4e5f6a7b8c9d0e3",
      "creditNoteNumber": "CN-001",
      "date": "2026-02-20",
      "customerId": {
        "_id": "64f1b2c3d4e5f6a7b8c9d0e1",
        "name": "John Doe"
      },
      "total": 5000,
      "reason": "Early checkout adjustment",
      "createdAt": "2026-02-20T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 25,
    "page": 1,
    "limit": 10,
    "totalPages": 3
  }
}

---

Get Credit Note by Code

GET /api/credit/:orgId/by-code/:code

Success Response 200

{
  "success": true,
  "data": {
    "_id": "64f1b2c3d4e5f6a7b8c9d0e3",
    "creditNoteNumber": "CN-001",
    "date": "2026-02-20",
    "customerId": {
      "_id": "64f1b2c3d4e5f6a7b8c9d0e1",
      "name": "John Doe",
      "email": "john@example.com"
    },
    "items": [
      {
        "description": "Room refund — Deluxe Suite",
        "quantity": 1,
        "rate": 5000,
        "taxId": "64f1b2c3d4e5f6a7b8c9d0e2",
        "amount": 5000
      }
    ],
    "total": 5000,
    "notes": "Refund for early checkout",
    "reason": "Early checkout adjustment"
  }
}

Error Response 404

{
  "success": false,
  "message": "Credit note not found"
}

---

Get Credit Note by ID

GET /api/credit/:orgId/:creditNoteId

Success Response 200

Same structure as Get Credit Note by Code.

Error Response 404

{
  "success": false,
  "message": "Credit note not found"
}

---

Update Credit Note

PUT /api/credit/:orgId/:creditNoteId/update

Request Body

{
  "items": [
    {
      "description": "Room refund — Deluxe Suite (revised)",
      "quantity": 1,
      "rate": 4500,
      "taxId": "64f1b2c3d4e5f6a7b8c9d0e2",
      "amount": 4500
    }
  ],
  "notes": "Revised refund amount",
  "reason": "Partial refund for early checkout"
}

Success Response 200

{
  "success": true,
  "message": "Credit note updated successfully",
  "data": {
    "_id": "64f1b2c3d4e5f6a7b8c9d0e3",
    "creditNoteNumber": "CN-001",
    "total": 4500,
    "notes": "Revised refund amount",
    "reason": "Partial refund for early checkout",
    "updatedAt": "2026-02-21T08:30:00.000Z"
  }
}

Error Response 404

{
  "success": false,
  "message": "Credit note not found"
}

---

Delete Credit Note

DELETE /api/credit/:orgId/:creditNoteId/delete

Success Response 200

{
  "success": true,
  "message": "Credit note deleted successfully"
}

Error Response 404

{
  "success": false,
  "message": "Credit note not found"
}