# Credit Notes Module

Generic credit notes module for tracking refunds, adjustments, and credits across entities (invoices, subscriptions, orders, etc).

## Features

- **Multi-entity support**: Track credit notes for any entity type
- **Status tracking**: Draft → Issued → Cancelled states
- **Amount validation**: Prevent credits exceeding entity balance
- **Auto-numbering**: Generate unique credit note numbers
- **Audit trail**: Track creation date and user

## Installation

```bash
composer require PortalPeople/surf-creditnotes
```

Register in your config:

```php
'modules' => [
    'credit-notes' => [
        'class' => 'PortalPeople\creditnotes\Module',
    ],
],
```

## Database Setup

```bash
php yii migrate --migrationPath=@app/NGauge_modules/credit-notes/migrations
```

## Usage

### Add Credit Notes to Your Entity

In your model, use the `HasCreditNotesTrait`:

```php
use PortalPeople\creditnotes\traits\HasCreditNotesTrait;

class MyEntity extends \yii\db\ActiveRecord
{
    use HasCreditNotesTrait;
    
    // ... your code ...
}
```

### Create & Issue Credit Note

```php
use PortalPeople\creditnotes\models\CreditNote;

$creditNote = new CreditNote([
    'entity_id' => $entity->id,
    'entity_type' => get_class($entity),
    'amount' => 50.00,
    'reason' => 'Partial refund',
]);

if ($creditNote->validate()) {
    $creditNote->issue(); // Generates number and sets to Issued
}
```

### Query Credit Notes

```php
// Get all credit notes for entity
$notes = $entity->getCreditNotes()->all();

// Get total credited amount
$credited = $entity->getTotalCreditAmount();

// Get remaining balance
$balance = $entity->getBalance();

// Check if entity can accept more credits
if ($entity->canAddCreditNote()) {
    // ...
}
```

## Version History

### v1.0.0 (2026-03-11)

- Initial release
- Multi-entity credit note support
- Draft/Issued/Cancelled states
- Audit trail tracking
