# `PhoenixKitBilling.Invoice`
[🔗](https://github.com/BeamLabEU/phoenix_kit_billing/blob/0.5.1/lib/phoenix_kit_billing/schemas/invoice.ex#L1)

Invoice schema for PhoenixKit Billing system.

Invoices are generated from orders and sent to customers for payment.
They include receipt functionality once payment is confirmed.

## Schema Fields

### Identity & Relations
- `user_uuid`: Foreign key to the user
- `order_uuid`: Foreign key to the source order (optional)
- `invoice_number`: Unique invoice identifier (e.g., "INV-2024-0001")
- `status`: Invoice status workflow

### Financial
- `subtotal`, `tax_amount`, `tax_rate`, `total`: Financial amounts
- `currency`: ISO 4217 currency code
- `due_date`: Payment due date

### Billing Details
- `billing_details`: Full snapshot of billing profile
- `line_items`: Copy of order line items
- `payment_terms`: Payment terms text
- `bank_details`: Bank account for payment

### Receipt
- `receipt_number`: Receipt identifier (generated after payment)
- `receipt_generated_at`: When receipt was generated
- `receipt_data`: Additional receipt data (PDF URL, etc.)

## Status Workflow

```
draft → sent → paid
            ↘
           overdue → paid
            ↘
            void
```

## Usage Examples

    # Generate invoice from order
    {:ok, invoice} = Billing.create_invoice_from_order(order)

    # Send invoice
    {:ok, invoice} = Billing.send_invoice(invoice)

    # Mark as paid (generates receipt)
    {:ok, invoice} = Billing.mark_invoice_paid(invoice)

    # Get receipt
    receipt = Billing.get_receipt(invoice)

# `billing_name`

Returns the billing name from billing_details snapshot.

# `changeset`

Creates a changeset for invoice creation.

# `editable?`

Checks if invoice can be edited.

# `from_order`

Creates an invoice from an order.

# `fully_paid?`

Checks if invoice is fully paid (paid_amount >= total).

# `has_payments?`

Checks if invoice has any payments (paid_amount > 0).

# `has_receipt?`

Checks if invoice has a receipt.

# `overdue?`

Checks if invoice is overdue.

# `paid_amount_changeset`

Changeset for updating paid_amount.

# `paid_changeset`

Changeset for marking invoice as paid and generating receipt.

# `payable?`

Checks if invoice can be marked as paid.

# `payment_methods`

Returns all unique payment methods used in transactions for this invoice.
Requires transactions to be preloaded.

## Examples

    iex> Invoice.payment_methods(invoice_with_transactions)
    ["bank", "stripe"]

    iex> Invoice.payment_methods(invoice_without_transactions)
    []

# `primary_payment_method`

Returns the primary payment method (most used in positive transactions).
Useful for display when there are multiple payment methods.
Requires transactions to be preloaded.

## Examples

    iex> Invoice.primary_payment_method(invoice)
    "stripe"

    iex> Invoice.primary_payment_method(invoice_without_transactions)
    nil

# `refundable?`

Checks if invoice can receive a refund (has payments).

# `remaining_amount`

Returns the remaining amount to be paid.

# `resendable?`

Checks if invoice can be resent (already sent, paid, or overdue).

# `sendable?`

Checks if invoice can be sent (first time - changes status to sent).

# `status_changeset`

Changeset for status transitions.

# `status_color`

Returns status badge color class.

# `status_label`

Returns human-readable status label.

# `voidable?`

Checks if invoice can be voided.

---

*Consult [api-reference.md](api-reference.md) for complete listing*