> ## Documentation Index
> Fetch the complete documentation index at: https://memberpulseptyltd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoicing Automation

> Automate invoice generation, delivery, and payment processing

Automate the creation, delivery, and management of invoices for memberships, events, and other billable items.

## Capabilities

| Action               | ROLE\_CLIENT\_ADMIN | ROLE\_CLIENT\_USER |
| -------------------- | ------------------- | ------------------ |
| View invoices        | ✅                   | ✅                  |
| Generate invoices    | ✅                   | ❌                  |
| Configure automation | ✅                   | ❌                  |
| Process refunds      | ✅                   | ❌                  |
| Export invoices      | ✅                   | ✅                  |

## Features

### Automatic Invoice Generation

Invoices are automatically generated for:

* **Membership Renewals** - Generated X days before expiry
* **Event Registrations** - Generated at registration
* **Course Purchases** - Generated at enrollment
* **Resource Downloads** - Generated for paid resources
* **Job Postings** - Generated when posting is submitted
* **Sponsorship Plans & Promotions** - Generated for sponsorship tiers, ad placements, and sponsored promotions

#### Acceptance Criteria

##### Frontend

* [ ] Invoice list with status filtering
* [ ] Invoice detail view with PDF preview
* [ ] Manual invoice creation form
* [ ] Bulk invoice generation
* [ ] Invoice export (PDF, CSV)
* [ ] Refund processing workflow

##### Backend / API

* [ ] Backend behavior supports this feature as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] Invoice numbers must be unique and sequential
* [ ] Cannot edit invoice after payment received
* [ ] Refund cannot exceed invoice amount
* [ ] Due date calculated from invoice date + payment terms
* [ ] Overdue status set automatically based on due date
* [ ] Voided invoices retained for audit purposes
* [ ] Tax calculated based on organization settings

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Invoice Configuration

<Tabs>
  <Tab title="Invoice Details">
    * Invoice number format (e.g., INV-YYYYMMDD-####)
    * Organization details (name, address, ABN)
    * Payment terms (due date calculation)
    * Tax configuration (rate, inclusion)
  </Tab>

  <Tab title="Branding">
    * Logo placement
    * Color scheme
    * Custom header/footer text
    * Terms and conditions
  </Tab>

  <Tab title="Delivery">
    * Auto-send on generation
    * Email template selection
    * CC/BCC addresses
    * Reminder schedule
  </Tab>
</Tabs>

#### Acceptance Criteria

##### Frontend

* [ ] Invoice settings configuration
* [ ] Reminder schedule configuration

##### Backend / API

* [ ] Backend behavior supports this feature as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Invoice Lifecycle

```
Draft → Sent → Viewed → Paid
                  ↓
              Overdue → Reminder → Paid/Written Off
```

#### Acceptance Criteria

##### Frontend

* [ ] UI supports the workflows described in this feature.

##### Backend / API

* [ ] Backend behavior supports this feature as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

### Payment Reminders

Configure automatic reminders:

| Reminder        | Default Timing    |
| --------------- | ----------------- |
| First reminder  | 3 days before due |
| Second reminder | On due date       |
| Overdue notice  | 7 days after due  |
| Final notice    | 14 days after due |

#### Acceptance Criteria

##### Frontend

* [ ] Payment recording interface

##### Backend / API

* [ ] Backend behavior supports this feature as documented.

##### Permissions

* [ ] Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

##### Business Rules

* [ ] All business rules for this feature are enforced.

##### Error Handling

* [ ] Error states return clear messages and appropriate HTTP status codes.

#### Data Model Cross‑Reference (Entities)

* Payment status / transaction records: [`Payment Transaction`](/entities/integration/payment-transaction)
* Unearned revenue recognition: [`Unearned Revenue`](/entities/integration/unearned-revenue)

## Implementation Contracts

### Backend (API)

```
GET    /api/invoices                         # List all invoices
POST   /api/invoices                         # Create manual invoice
GET    /api/invoices/{id}                    # Get invoice details
PUT    /api/invoices/{id}                    # Update invoice
DELETE /api/invoices/{id}                    # Void invoice

GET    /api/invoices/{id}/pdf                # Download PDF
POST   /api/invoices/{id}/send               # Send/resend invoice
POST   /api/invoices/{id}/record-payment     # Record manual payment
POST   /api/invoices/{id}/refund             # Process refund

GET    /api/invoices/settings                # Get invoice settings
PUT    /api/invoices/settings                # Update settings

POST   /api/invoices/bulk-generate           # Generate multiple invoices
POST   /api/invoices/export                  # Export invoices
```

### Data Model

```typescript theme={null}
interface Invoice {
  id: string;
  invoiceNumber: string;
  memberId: string;
  memberName: string;
  memberEmail: string;
  
  // Line items
  items: InvoiceItem[];
  
  // Amounts
  subtotal: number;
  taxRate: number;
  taxAmount: number;
  total: number;
  
  // Dates
  invoiceDate: string;
  dueDate: string;
  paidDate?: string;
  
  // Status
  status: 'draft' | 'sent' | 'viewed' | 'paid' | 'overdue' | 'voided';
  
  // Payment
  paymentMethod?: string;
  transactionId?: string;
  
  // Related
  relatedType: 'membership' | 'event' | 'course' | 'resource' | 'job' | 'sponsorship';
  relatedId: string;
  
  createdAt: string;
  updatedAt: string;
}

interface InvoiceItem {
  description: string;
  quantity: number;
  unitPrice: number;
  amount: number;
}
```

### Error Handling

| Error                 | HTTP Status | Message                               |
| --------------------- | ----------- | ------------------------------------- |
| Already paid          | 400         | "Cannot modify paid invoice"          |
| Refund exceeds amount | 400         | "Refund amount exceeds invoice total" |
| Invalid due date      | 400         | "Due date must be after invoice date" |
| Voided invoice        | 400         | "Invoice has been voided"             |