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

Order schema for PhoenixKit Billing system.

Manages orders with line items, amounts, and billing information.
Orders serve as the primary document for tracking what users purchased.

## Schema Fields

### Identity & Relations
- `user_uuid`: Foreign key to the user who placed the order
- `billing_profile_uuid`: Foreign key to the billing profile used
- `order_number`: Unique order identifier (e.g., "ORD-2024-0001")
- `status`: Order status workflow

### Payment
- `payment_method`: Payment method (Phase 1: "bank" only)
- `currency`: ISO 4217 currency code

### Line Items
- `line_items`: JSONB array of items purchased

### Financial
- `subtotal`: Sum of line items before tax/discount
- `tax_amount`: Calculated tax amount
- `tax_rate`: Applied tax rate (0.20 = 20%)
- `discount_amount`: Discount applied
- `discount_code`: Coupon/referral code used
- `total`: Final amount to be paid

### Snapshots & Notes
- `billing_snapshot`: Copy of billing profile at order time
- `notes`: Customer-visible notes
- `internal_notes`: Admin-only notes

## Status Workflow

```
draft → pending → confirmed → paid
               ↘         ↘
             cancelled   refunded
```

## Line Item Structure

```json
[
  {
    "name": "Pro Plan - Monthly",
    "description": "Professional subscription plan",
    "quantity": 1,
    "unit_price": "99.00",
    "total": "99.00",
    "sku": "PLAN-PRO-M"
  }
]
```

## Usage Examples

    # Create an order
    {:ok, order} = Billing.create_order(user, %{
      billing_profile_uuid: profile.uuid,
      currency: "EUR",
      line_items: [
        %{name: "Pro Plan", quantity: 1, unit_price: "99.00", total: "99.00"}
      ],
      subtotal: "99.00",
      total: "99.00"
    })

    # Confirm order
    {:ok, order} = Billing.confirm_order(order)

    # Mark as paid
    {:ok, order} = Billing.mark_order_paid(order)

# `calculate_totals`

Calculates totals from line items.

Returns `{subtotal, tax_amount, total}` as Decimals.

# `calculate_totals_for_country`

Calculates totals with automatic tax rate from country.

Uses standard VAT rate from BeamLabCountries based on the billing country.
Returns `{subtotal, tax_amount, total}` as Decimals.

## Examples

    iex> items = [%{"total" => "100.00"}]
    iex> {subtotal, tax, total} = Order.calculate_totals_for_country(items, "EE")
    iex> Decimal.to_string(tax)
    "20.00"
    iex> Decimal.to_string(total)
    "120.00"

# `cancellable?`

Checks if order can be cancelled.

# `changeset`

Creates a changeset for order creation.

# `editable?`

Checks if order can be edited (is in draft or pending status).

# `get_country_tax_rate`

Gets the standard VAT rate for a country as a Decimal.

## Examples

    iex> Order.get_country_tax_rate("EE")
    #Decimal<0.20>

    iex> Order.get_country_tax_rate("US")
    #Decimal<0>

# `payable?`

Checks if order can be marked as paid.

# `status_changeset`

Changeset for status transitions.

# `status_color`

Returns status badge color class.

# `status_label`

Returns human-readable status label.

---

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