Transactions Domain - Services Documentation

class TransactionService:
    """
    Service class encapsulating transaction business logic.
    All public methods use @transaction.atomic for data integrity.
    """

class TransactionServiceError(Exception):
    """Base exception for transaction service errors"""
    pass

class InsufficientInventoryError(TransactionServiceError):
    """Raised when requested quantity exceeds available inventory"""
    pass

@transaction.atomic
def create_transaction(self, store, employee=None, customer=None, source_system=None) -> SaleTransaction:

return SaleTransaction.objects.create_transaction(
    store=store,
    employee=employee,
    customer=customer,
    source_system=source_system,
)

@staticmethod
def create_transaction_with_real_data():

{
    'success': True,
    'transaction_id': 'TXN-20251117-A3B4C5D6',
    'total_amount': '59.99',
    'message': 'Transaction created and completed successfully'
}

store = Store.objects.first()
employee = Employee.objects.first()
product_variant = ProductVariant.objects.filter(
    inventory__gt=0,
    price__gt=0
).first()
promo_code = PromoCode.objects.filter(isActive=True).first()

sale_transaction = SaleTransaction.objects.create(
    transactionId=transaction_id,
    store=store,
    employee=employee,
    status='pending'
)

line_item = SaleLineItem.objects.create(
    transaction=sale_transaction,
    productVariant=product_variant,
    quantity=1,
    unitPrice=product_variant.price,
    totalPrice=product_variant.price
)

if promo_code:
    sale_transaction.appliedPromoCodes.add(promo_code)

sale_transaction.recalculate_totals(commit=True)

payment_method = PaymentMethod.objects.filter(
    method_type='cash',
    is_active=True
).first()

payment = TransactionPayment.objects.create(
    transaction=sale_transaction,
    paymentMethod=payment_method,
    amount=sale_transaction.totalAmount,
    status='succeeded'
)

sale_transaction.status = 'completed'
sale_transaction.completedAt = timezone.now()
sale_transaction.save()

@transaction.atomic
def add_product_to_transaction(
    self,
    transaction_id: str,
    product_variant_id: uuid.UUID,
    quantity: int,
    unit_price: Decimal = None
) -> SaleTransaction:

line_item = SaleLineItem.objects.create(
    transaction=sale_transaction,
    productVariant=product_variant,
    quantity=quantity,
    unitPrice=unit_price,
    totalPrice=total_price,
    lineDiscount=line_discount,
)

# Populate the active vertical's compliance snapshot (if any) via the agnostic seam
on_line_item_added(line_item, store=sale_transaction.store)

sale_transaction.recalculate_totals()

with disable_sync_signals():
    # Create transaction
    transaction = self.transaction_service.create_transaction(...)

    # Add multiple line items WITHOUT recalculating each time
    for item_data in line_items:
        self.transaction_service.add_product_to_transaction_without_recalc(
            transaction_id=transaction.transactionId,
            product_variant_id=item_data.get('productVariant'),
            quantity=item_data.get('quantity', 1)
        )

# Recalculate once at the end
transaction.recalculate_totals(commit=True)

@transaction.atomic
def update_line_item_quantity(
    self,
    transaction_id: str,
    line_item_id: int,
    new_quantity: int
) -> SaleTransaction:

txn = SaleTransaction.objects.get(transactionId=transaction_id)
line_item = SaleLineItem.objects.get(id=line_item_id, transaction=txn)

# Check inventory for new quantity
if not self._check_inventory_availability(
    line_item.productVariant,
    new_quantity,
    txn.store
):
    raise InsufficientInventoryError("Insufficient inventory")

# Update quantity and total
line_item.quantity = new_quantity
line_item.totalPrice = line_item.unitPrice * new_quantity - line_item.lineDiscount
line_item.save()

# Recalculate transaction totals
txn.recalculate_totals(commit=True)

return txn

@transaction.atomic
def remove_product_from_transaction(
    self,
    transaction_id: str,
    line_item_id: str
) -> SaleTransaction:
    return self.remove_line_item(transaction_id, line_item_id)

txn = SaleTransaction.objects.get(transactionId=transaction_id)
line_item = SaleLineItem.objects.get(id=line_item_id, transaction=txn)

# Delete the line item
line_item.delete()

# Recalculate transaction totals
txn.recalculate_totals(commit=True)

return txn

@transaction.atomic
def apply_promo_code(
    self,
    transaction_id: str,
    promo_code: str,
    store_id: str = None
) -> SaleTransaction:

txn = SaleTransaction.objects.get(transactionId=transaction_id)

promo = PromoCode.objects.get(code=promo_code.upper(), isActive=True)

txn.appliedPromoCodes.add(promo)
logger.info(f"Applied promo code {promo_code} to transaction {transaction_id}")

txn.recalculate_totals(commit=True)

txn = SaleTransaction.objects.get(transactionId=transaction_id)
promo = PromoCode.objects.get(code=promo_code.upper())

# Remove promo code
txn.appliedPromoCodes.remove(promo)
logger.info(f"Removed promo code {promo_code} from transaction {transaction_id}")

# Recalculate totals (discounts removed)
txn.recalculate_totals(commit=True)

return txn

@transaction.atomic
def apply_line_item_discount(
    self,
    transaction_id: str,
    line_item_id: int,
    discount_amount: Decimal,
    employee=None
) -> SaleTransaction:

txn = SaleTransaction.objects.get(transactionId=transaction_id)
line_item = SaleLineItem.objects.get(id=line_item_id, transaction=txn)

# Validate discount amount
if discount_amount < 0:
    raise TransactionServiceError("Discount amount cannot be negative")

if discount_amount > line_item.totalPrice:
    raise TransactionServiceError("Discount cannot exceed line item total")

# Apply discount
line_item.lineDiscount = discount_amount
line_item.totalPrice = (line_item.unitPrice * line_item.quantity) - discount_amount
line_item.save()

logger.info(
    f"Applied \${discount_amount} discount to line item {line_item_id} "
    f"in transaction {transaction_id} by employee {employee.id if employee else 'system'}"
)

# Recalculate transaction totals
txn.recalculate_totals(commit=True)

return txn

@transaction.atomic
def complete_transaction(
    self,
    transaction_id: str,
    payment_method_id: int = None,
    amount_paid: Decimal = None,
) -> SaleTransaction:

@transaction.atomic
def void_transaction(
    self,
    transaction_id: str,
    reason: str = "",
    employee=None
) -> SaleTransaction:

successful_payments = sale_transaction.payment_records.filter(status='succeeded')
for payment in successful_payments:
    from nextango.apps.payments.services import RefundService
    success, refund, message = RefundService.process_refund(
        payment_id=payment.id,
        amount=payment.amount,
        reason=f'Transaction voided: {reason}',
    )
    # finally block always runs:
    payment.status = 'voided'

def _check_inventory_availability(
    self,
    product_variant: ProductVariant,
    requested_quantity: int,
    store
) -> bool:

inventory_level = InventoryLevel.objects.get(
    variant_sku=product_variant.sku,
    product=product_variant.product,
    store=store,
    is_active=True
)

# Check available quantity (stock_on_hand - stock_reserved)
available_quantity = inventory_level.stock_on_hand - inventory_level.stock_reserved

return available_quantity >= requested_quantity

{
    'transaction_id': 'TXN-20251117-A3B4C5D6',
    'store': {
        'id': 'uuid',
        'name': 'Columbus Main Street',
        'store_code': 'COL001'
    },
    'employee': {
        'id': 'uuid',
        'name': 'John Doe'
    },
    'customer': {
        'id': 'uuid',
        'name': 'Alice Smith'
    },
    'line_items': [
        {
            'id': 'uuid',
            'sku': 'WIDG-001',
            'name': 'Widget Pro',
            'quantity': 2,
            'unit_price': '29.99',
            'line_discount': '0.00',
            'total_price': '59.98'
        }
    ],
    'totals': {
        'subtotal': '59.98',
        'tax_amount': '4.80',
        'order_level_discount': '0.00',
        'total_amount': '64.78'
    },
    'payments': [
        {
            'id': 'uuid',
            'amount': '64.78',
            'method': 'Credit Card',
            'status': 'succeeded'
        }
    ],
    'status': 'completed',
    'timestamps': {
        'created_at': '2025-11-17T10:00:00Z',
        'completed_at': '2025-11-17T10:05:00Z'
    }
}

class ReturnService:
    """
    Service class for processing product returns and refunds.
    Handles return creation, validation, refund processing, and inventory adjustments.
    """

┌─────────────────────────────────────────────────────────────┐
│ Refund-First Return Architecture                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Validate Return Request                                 │
│     ↓                                                        │
│  2. Calculate Total Return Value                            │
│     ↓                                                        │
│  3. Process Refund(s) FIRST ← Creates Refund records       │
│     │  (sales_return=None at this point)                   │
│     ↓                                                        │
│  4. Create Return Record ← Creates Return record            │
│     ↓                                                        │
│  5. Link Refunds to Return ← Updates Refund.sales_return   │
│     ↓                                                        │
│  6. Create ReturnLineItems                                  │
│     ↓                                                        │
│  7. Mark Return as Processed                                │
│                                                              │
└─────────────────────────────────────────────────────────────┘

# Step 2: Calculate BEFORE creating return
total_return_value = self._calculate_return_value(return_items_data, original_transaction)

# Step 3: Process refund FIRST (no return exists yet)
created_refunds = self._process_multi_payment_refund(
    original_transaction,
    total_return_value,
    refund_to_payment_ids,
    reason
)
# At this point: Refund records exist, but sales_return FK is NULL

# Step 4: Create return AFTER refunds processed
sales_return = Return.objects.create_return(
    original_transaction=original_transaction,
    employee=employee,
    reason=reason
)

# Step 5: Link refunds to return
for refund in created_refunds:
    refund.sales_return = sales_return
    refund.save(update_fields=['sales_return'])

class Refund(models.Model):
    sales_return = models.ForeignKey(
        'transactions.Return',
        on_delete=models.SET_NULL,
        null=True,  # Allows refund-first flow
        blank=True,
        related_name='refunds'
    )

class ReturnValidationError(Exception):
    """Raised when return request validation fails"""
    pass

@transaction.atomic
def process_return(
    self,
    original_transaction: SaleTransaction,
    return_items_data: List[Dict[str, Any]],
    reason: str,
    employee,
    refund_method: str,
    refund_to_payment_ids: List[str] = None
) -> Return:

[
    {
        'transaction_item_id': 'line-item-uuid',
        'quantity': 2,
        'reason': 'changed_mind',  # damaged, wrong_size, unwanted_gift, defective, etc.
        'disposition': 'sellable'   # sellable, defective, quarantine, damaged_out, vendor_return
    }
]

self._validate_return_request(
    original_transaction,
    return_items_data,
    refund_method,
    refund_to_payment_ids
)

total_return_value = self._calculate_return_value(
    return_items_data,
    original_transaction
)

created_refunds = []
if refund_method == 'original':
    # Distribute refund across multiple payments
    created_refunds = self._process_multi_payment_refund(
        original_transaction,
        total_return_value,
        refund_to_payment_ids,
        reason
    )
# Store credit processed later (after return exists)

sales_return = Return.objects.create_return(
    original_transaction=original_transaction,
    employee=employee,
    reason=reason
)

for refund in created_refunds:
    refund.sales_return = sales_return
    refund.save(update_fields=['sales_return'])

return_items = self._create_return_items(
    sales_return,
    return_items_data
)

if refund_method == 'store_credit':
    self._process_store_credit_refund(
        sales_return,
        total_return_value
    )

sales_return.mark_as_processed(processed_by_employee=employee)

self._update_transaction_status(original_transaction)
# Sets to 'refunded' or 'partially_refunded' based on return value

def _process_multi_payment_refund(
    self,
    original_transaction: SaleTransaction,
    total_refund_amount: Decimal,
    payment_ids: List[str],
    reason: str
) -> List[Refund]:

payments_with_balance = []
for payment_id in payment_ids:
    payment = TransactionPayment.objects.get(id=payment_id)

    # Calculate already refunded amount
    total_refunded = Refund.objects.filter(
        payment=payment,
        status='succeeded'
    ).aggregate(total=Sum('amount'))['total'] or Decimal('0.00')

    # Calculate remaining refundable balance
    remaining_balance = payment.amount - total_refunded

    if remaining_balance > Decimal('0.00'):
        payments_with_balance.append({
            'payment': payment,
            'remaining_balance': remaining_balance
        })

payments_with_balance.sort(key=lambda x: x['remaining_balance'])

total_capacity = sum(p['remaining_balance'] for p in payments_with_balance)

if total_capacity < total_refund_amount:
    raise ReturnValidationError(
        f"Insufficient refundable balance. "
        f"Available: \${total_capacity:.2f}, "
        f"Requested: \${total_refund_amount:.2f}"
    )

created_refunds = []
remaining_to_refund = total_refund_amount

for payment_data in payments_with_balance:
    if remaining_to_refund <= Decimal('0.00'):
        break  # Refund fully distributed

    payment = payment_data['payment']
    available = payment_data['remaining_balance']

    # Refund up to available balance
    refund_amount = min(remaining_to_refund, available)

    # Process refund through RefundService
    success, refund, message = RefundService.process_refund(
        payment_id=str(payment.id),
        amount=refund_amount,
        reason=f'Return for transaction {original_transaction.transactionId}: {reason}',
        sales_return=None  # Will be linked later in refund-first flow
    )

    if not success:
        raise ReturnValidationError(f"Refund failed: {message}")

    created_refunds.append(refund)
    remaining_to_refund -= refund_amount

return created_refunds

# Original transaction: $150 total
# Payment 1 (Cash): $50
# Payment 2 (Card): $100
# Refund amount: $150

# Distribution:
# Step 1: Refund $50 to Cash (fully refunds payment 1)
# Step 2: Refund $100 to Card (fully refunds payment 2)
# Result: Both payments fully refunded

# Original transaction: $200 total
# Payment 1 (Cash): $50
# Payment 2 (Card 1): $75
# Payment 3 (Card 2): $75
# Refund amount: $100

# Distribution (smallest first):
# Step 1: Refund $50 to Cash (fully refunds payment 1)
# Step 2: Refund $50 to Card 1 (partially refunds payment 2: $50/$75)
# Result: Cash fully refunded, Card 1 partially refunded, Card 2 untouched

# Original transaction: $150 total
# Payment 1 (Cash): $50 (already refunded $20)
# Payment 2 (Card): $100 (no refunds yet)
# New refund amount: $80

# Remaining balances:
# Payment 1: $30 remaining ($50 - $20)
# Payment 2: $100 remaining

# Distribution (smallest remaining first):
# Step 1: Refund $30 to Cash (fully refunds remaining balance)
# Step 2: Refund $50 to Card (partially refunds payment 2: $50/$100)
# Result: Cash fully refunded, Card partially refunded

if original_transaction.status not in [
    SaleTransaction.Status.COMPLETED,
    SaleTransaction.Status.PARTIALLY_REFUNDED
]:
    raise ReturnValidationError(
        f"Can only return completed transactions. Current status: {original_transaction.status}"
    )

if not return_items_data or len(return_items_data) == 0:
    raise ReturnValidationError("At least one item must be returned")

if refund_method not in ['original', 'store_credit']:
    raise ReturnValidationError(
        f"Invalid refund method: {refund_method}. Must be 'original' or 'store_credit'"
    )

transaction_items = {str(item.id): item for item in original_transaction.line_items.all()}

for item_data in return_items_data:
    self._validate_return_item_data(item_data, transaction_items)

total_return_value = self._calculate_return_value(return_items_data, original_transaction)

if total_return_value > original_transaction.get_refundable_amount():
    raise ReturnValidationError(
        f"Return value (\${total_return_value}) exceeds refundable amount "
        f"(\${original_transaction.get_refundable_amount()})"
    )

required_fields = ['transaction_item_id', 'quantity', 'reason', 'disposition']
for field in required_fields:
    if field not in item_data:
        raise ReturnValidationError(f"Missing required field: {field}")

item_id = str(item_data['transaction_item_id'])
if item_id not in transaction_items:
    raise ReturnValidationError(f"Item {item_id} not found in original transaction")

original_item = transaction_items[item_id]
return_quantity = int(item_data['quantity'])

if return_quantity <= 0:
    raise ReturnValidationError("Return quantity must be positive")

if return_quantity > original_item.quantity:
    raise ReturnValidationError(
        f"Cannot return {return_quantity} of item {item_id}. "
        f"Only {original_item.quantity} were purchased"
    )

valid_reasons = ['damaged', 'wrong_size', 'unwanted_gift', 'defective', 'not_as_described', 'changed_mind']
if item_data['reason'] not in valid_reasons:
    raise ReturnValidationError(f"Invalid return reason: {item_data['reason']}")

valid_dispositions = ['sellable', 'defective', 'quarantine', 'damaged_out', 'vendor_return']
if item_data['disposition'] not in valid_dispositions:
    raise ReturnValidationError(f"Invalid disposition: {item_data['disposition']}")

succeeded_payments = original_transaction.payment_records.filter(
    status='succeeded'
).order_by('created_at')

if not succeeded_payments.exists():
    raise ReturnValidationError("No succeeded payments found to refund")

if refund_to_payment_ids:
    # Refund specific payments
    payments_to_refund = succeeded_payments.filter(
        id__in=refund_to_payment_ids
    )
else:
    # Refund all payments
    payments_to_refund = succeeded_payments

remaining_refund = total_value

for payment in payments_to_refund:
    # Calculate refund amount for this payment
    refund_amount = min(remaining_refund, payment.amount)

    # Create refund record
    from nextango.apps.payments.models import Refund
    refund = Refund.objects.create(
        payment=payment,
        sales_return=sales_return,
        amount=refund_amount,
        status='succeeded',  # Simplified - real implementation processes with payment gateway
        processedAt=timezone.now()
    )

    remaining_refund -= refund_amount

    if remaining_refund <= 0:
        break

if remaining_refund > Decimal('0.01'):  # Allow for rounding
    raise ReturnValidationError(
        f"Could not fully process refund. Remaining: \${remaining_refund}"
    )

customer = sales_return.originalSaleId.customer

if not customer:
    raise ReturnValidationError("Cannot issue store credit without customer")

# Create store credit
store_credit = StoreCredit.objects.create_store_credit(
    customer=customer,
    amount=total_value,
    expiration_days=365,  # 1 year expiration
    source_return=sales_return
)

# Create store credit transaction ledger entry
from .models import StoreCreditTransaction
StoreCreditTransaction.objects.create(
    store_credit=store_credit,
    transactionType='issue',
    amount=total_value,
    salesReturn=sales_return,
    notes=f"Store credit issued for return {sales_return.returnId}"
)

logger.info(
    f"Issued \${total_value} store credit ({store_credit.creditId}) "
    f"to customer {customer.id} for return {sales_return.returnId}"
)

total_value = Decimal('0.00')
transaction_items = {
    str(item.id): item
    for item in original_transaction.line_items.all()
}

for item_data in return_items_data:
    item_id = str(item_data['transaction_item_id'])
    original_item = transaction_items[item_id]
    return_quantity = int(item_data['quantity'])

    # Calculate proportional value
    # (unit price - proportional discount) * return quantity
    unit_value = original_item.unitPrice
    if original_item.lineDiscount > 0:
        # Proportional discount per unit
        discount_per_unit = original_item.lineDiscount / original_item.quantity
        unit_value -= discount_per_unit

    item_return_value = unit_value * return_quantity
    total_value += item_return_value

    logger.info(
        f"Return item {item_id}: {return_quantity} units @ \${unit_value} = \${item_return_value}"
    )

logger.info(f"Total return value calculated: \${total_value}")
return total_value

return_items = []

for item_data in return_items_data:
    # Get original sale line item
    original_line_item = SaleLineItem.objects.get(
        id=item_data['transaction_item_id']
    )

    # Calculate return price (proportional to quantity)
    unit_value = original_line_item.unitPrice
    if original_line_item.lineDiscount > 0:
        discount_per_unit = original_line_item.lineDiscount / original_line_item.quantity
        unit_value -= discount_per_unit

    return_price = unit_value * item_data['quantity']

    # Create return line item
    return_item = ReturnLineItem.objects.create(
        sales_return=sales_return,
        original_sale_line_item=original_line_item,
        quantity=item_data['quantity'],
        returnPrice=return_price,
        reason=item_data['reason'],
        disposition=item_data['disposition']
    )

    return_items.append(return_item)

    logger.info(
        f"Created return line item: {return_item.skuSnapshot} "
        f"x{return_item.quantity} @ \${return_price}"
    )

return return_items

refundable_amount = transaction.get_refundable_amount()

if refundable_amount <= Decimal('0.01'):  # Fully refunded (allow rounding)
    transaction.status = SaleTransaction.Status.REFUNDED
    logger.info(f"Transaction {transaction.transactionId} fully refunded")
else:
    transaction.status = SaleTransaction.Status.PARTIALLY_REFUNDED
    logger.info(
        f"Transaction {transaction.transactionId} partially refunded. "
        f"Remaining refundable: \${refundable_amount}"
    )

transaction.save(update_fields=['status'])

[
    {
        'line_item_id': 'uuid',
        'sku': 'WIDG-001',
        'name': 'Widget Pro',
        'quantity_purchased': 2,
        'quantity_already_returned': 1,
        'quantity_returnable': 1,
        'unit_price': '29.99',
        'max_refund_value': '29.99'
    }
]

{
    'return_id': 'RET-20251117-F7E8D9C0',
    'original_transaction_id': 'TXN-20251117-A3B4C5D6',
    'status': 'processed',
    'reason': 'Customer changed mind',
    'employee': {
        'id': 'uuid',
        'name': 'John Doe'
    },
    'items': [
        {
            'sku': 'WIDG-001',
            'name': 'Widget Pro',
            'quantity': 2,
            'return_price': '59.98',
            'reason': 'changed_mind',
            'disposition': 'sellable'
        }
    ],
    'refunds': [
        {
            'amount': '59.98',
            'payment_method': 'Credit Card',
            'status': 'succeeded',
            'processed_at': '2025-11-17T10:35:00Z'
        }
    ],
    'store_credits': [
        {
            'credit_id': 'SC-20251117-B1C2D3E4',
            'amount': '59.98',
            'expiration_date': '2026-11-17'
        }
    ],
    'total_value': '59.98',
    'timestamps': {
        'created_at': '2025-11-17T10:30:00Z',
        'processed_at': '2025-11-17T10:35:00Z'
    }
}

expected_amount = opening_amount + sales - refunds + pay_ins - pay_outs
variance = counted_amount - expected_amount

class FulfillmentService:
    """
    Service for managing fulfillment records.
    Coordinates Fulfillment and Shipment creation during checkout.
    """

@staticmethod
def create_from_checkout(transaction, checkout_data):

{
    'email': '[email protected]',
    'shipping_address': {
        'firstName': 'John',
        'lastName': 'Doe',
        'address': '123 Main St',
        'city': 'Columbus',
        'region': 'OH',
        'postalCode': '43215',
        'country': 'US',
        'phone': '555-1234'
    },
    'delivery_method': {
        'id': 'standard-shipping',
        'title': 'Standard Shipping',
        'turnaround': '5-7 business days',
        'price': '$7.99',
        'priceValue': 7.99
    }
}

{
    'billing_address': {...},           # If billing_same_as_shipping is False
    'billing_same_as_shipping': True,   # Default True
    'payment_details': {
        'nameOnCard': 'John Doe',
        'cardNumber': '4111111111111111',  # Only last 4 stored
        'cardType': 'Visa'
    },
    'shipping_cost': Decimal('7.99')
}

@staticmethod
def create_initial_shipment(fulfillment, transaction):

@staticmethod
def create_split_shipment(fulfillment_id, line_item_ids, carrier_info=None):

# Order has items from two warehouses
shipment1 = FulfillmentService.create_split_shipment(
    fulfillment_id=fulfillment.id,
    line_item_ids=[item1.id, item2.id],
    carrier_info={'carrier': 'UPS', 'tracking': '1Z123456'}
)

shipment2 = FulfillmentService.create_split_shipment(
    fulfillment_id=fulfillment.id,
    line_item_ids=[item3.id],
    carrier_info={'carrier': 'FedEx', 'tracking': '794644'}
)

@staticmethod
def update_shipment_status(shipment_id, new_status, **kwargs):

# Mark as shipped with tracking
shipment = FulfillmentService.update_shipment_status(
    shipment_id=shipment.id,
    new_status='shipped',
    carrier_name='UPS',
    tracking_number='1Z999AA10123456784'
)

# Mark as delivered
shipment = FulfillmentService.update_shipment_status(
    shipment_id=shipment.id,
    new_status='delivered'
)

{'success': True}                           # on success
{'success': False, 'error': '<message>'}    # on failure