Transactions Domain - Views Documentation

queryset = SaleTransaction.objects.all()
serializer_class = SaleTransactionSerializer
lookup_field = 'transactionId'
authentication_classes = [PosGatewayAuthentication, WebSessionAuthentication]
permission_classes = [IsAuthenticated]
filter_backends = [filters.SearchFilter, filters.OrderingFilter]
search_fields = ['transactionId', 'customer__user__name']
ordering_fields = ['created_at', 'totalAmount']
ordering = ['-created_at']

def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)
    self.transaction_service = TransactionService()
    self.payment_service = PaymentService()
    self.validation_service = TransactionValidationService()

def get_queryset(self):
    queryset = super().get_queryset()

    # Filter by status
    status_param = self.request.query_params.get('status')
    if status_param:
        queryset = queryset.filter(status=status_param)

    # Filter by store (accepts either Django UUID or Sanity ID)
    store_param = self.request.query_params.get('store')
    if store_param:
        # Try filtering by Django ID first, then fall back to sanity_id
        queryset = queryset.filter(Q(store__id=store_param) | Q(store__sanity_id=store_param))

    return queryset.select_related('store', 'customer').prefetch_related('line_items')

# Extract store from JWT session (POS Gateway authentication)
if hasattr(request, 'auth') and request.auth:
    store_id = request.auth.get('store_id')
    if store_id:
        store = Store.objects.get(sanity_id=store_id)
        logger.info(f"Using store from JWT session: {store.name}")

# Fallback to provided store_id
if not store and validated_data.get('store_id'):
    store = Store.objects.get(id=validated_data['store_id'])

# Try Employee record first
try:
    employee_record = Employee.objects.get(id=validated_data['employee_id'])
    employee_user = employee_record.user
except Employee.DoesNotExist:
    # Fall back to Manager record
    manager_record = Manager.objects.get(id=validated_data['employee_id'])
    employee_user = manager_record.user

from nextango.apps.integrations.tasks.signal_management import disable_sync_signals

with disable_sync_signals():
    # Create transaction
    transaction = self.transaction_service.create_transaction(
        store=store,
        employee=employee_user,
        customer=customer
    )

    # Add line items (batched to prevent duplicate sync triggers)
    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),
            unit_price=item_data.get('unitPrice')  # Optional - uses variant price if None
        )

    # Apply promo codes
    for promo_code_str in applied_promo_codes:
        promo_code = PromoCode.objects.get(code=promo_code_str.upper(), isActive=True)
        transaction.appliedPromoCodes.add(promo_code)

# CALCULATE ALL TOTALS SERVER-SIDE (subtotal, tax, discounts, total)
# This is the ONLY source of financial calculations - never trust client
if line_items:
    transaction.recalculate_totals(commit=True)
    logger.info(
        f"Calculated transaction totals - "
        f"{transaction.transactionId}: "
        f"Subtotal \${transaction.subtotal}, "
        f"Tax \${transaction.taxAmount}, "
        f"Discount \${transaction.orderLevelDiscount}, "
        f"Total \${transaction.totalAmount}"
    )

{
    "storeId": "uuid-here",
    "employeeId": "uuid-here",
    "customerId": "uuid-here",
    "line_items": [
        {
            "productVariant": "variant-uuid",
            "quantity": 2,
            "unitPrice": "29.99"
        }
    ],
    "appliedPromoCodes": ["SPRING20"],
    "subtotal": 0,  // IGNORED by backend
    "taxAmount": 0,  // IGNORED by backend
    "totalAmount": 0  // IGNORED by backend
}

{
    "product_variant_id": "uuid-here",
    "quantity": 2,
    "unit_price": "29.99"  // Optional - uses variant price if not provided
}

@action(detail=True, methods=['post'])
@handle_view_exception
def add_item(self, request, transactionId=None):
    transaction = self.get_object()
    serializer = AddSaleLineItemSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)
    validated_data = serializer.validated_data

    self.validation_service.validate_add_item_request(validated_data, transaction, request)
    try:
        updated_transaction = self.transaction_service.add_product_to_transaction(
            transaction_id=transaction.transactionId, **validated_data
        )
        response_serializer = self.get_serializer(updated_transaction)
        return Response(response_serializer.data, status=status.HTTP_200_OK)
    except TransactionServiceError as e:
        raise BusinessLogicException(str(e))

{
    "line_item_id": "uuid-here"
}

{
    "line_item_id": "uuid-here",
    "quantity": 5
}

{
    "line_item_id": "uuid-here",
    "discount_amount": "5.00"
}

{
    "promo_code": "SPRING20"
}

@action(detail=True, methods=['post'])
@handle_view_exception
def apply_promo_code(self, request, transactionId=None):
    transaction = self.get_object()

    validated_data = self.validation_service.validate_promo_code_request(
        request.data, transaction, request
    )

    try:
        updated_transaction = self.transaction_service.apply_promo_code(
            transaction_id=transactionId,
            promo_code=validated_data['promo_code'],
            store_id=str(transaction.store.id) if transaction.store else None
        )

        response_serializer = self.get_serializer(updated_transaction)
        return Response(response_serializer.data, status=status.HTTP_200_OK)

    except TransactionServiceError as e:
        raise BusinessLogicException(str(e))

{
    "promo_code": "SPRING20"
}

{
    "transaction_id": "TXN-20251117-A3B4C5D6",
    "order_level_discount": 10.00,
    "applied_promo_codes": [
        {
            "code": "SPRING20",
            "name": "Spring Sale 2025",
            "discount_type": "percentage"
        }
    ],
    "line_item_promotions": [
        {
            "line_item_id": "uuid-here",
            "product_name": "Widget Pro",
            "sku": "WIDG-001",
            "promotions": [
                {
                    "promo_code": "SPRING20",
                    "campaign_name": "Spring Sale 2025",
                    "discount_amount": "5.99",
                    "discount_type": "percentage",
                    "applied_at": "2025-11-17T10:30:00Z"
                }
            ]
        }
    ]
}

{
    "payment_method_id": 1,
    "amount": "59.99",  // Optional - uses transaction total if not provided
    "tendered_amount": "60.00"  // Optional - for change calculation
}

@action(detail=True, methods=['post'])
@handle_view_exception
def process_payment(self, request, transactionId=None):
    transaction = self.get_object()
    serializer = ProcessPaymentRequestSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)
    validated_data = serializer.validated_data

    self.validation_service.validate_payment_request(validated_data, transaction, request)
    try:
        payment = self.transaction_service.process_payment(
            transaction_id=transactionId, **validated_data
        )
        payment_serializer = TransactionPaymentSerializer(payment)
        return Response(payment_serializer.data, status=status.HTTP_201_CREATED)
    except (TransactionServiceError, PaymentProcessingError) as e:
        SecurityEventLogger.log_payment_security_event(
            'payment_processing_failure', transactionId, f"Payment failed: {str(e)}",
            request, {'payment_amount': str(validated_data['amount'])}
        )
        raise PaymentSecurityException("Payment processing failed")

{
    "reason": "Customer cancelled order",
    "manager_override": true
}

{
    "total_amount": "59.99",
    "paid_amount": "59.99",
    "balance": "0.00",
    "payments": [
        {
            "amount": "59.99",
            "method": "credit_card",
            "status": "succeeded",
            "processed_at": "2025-11-17T10:30:00Z"
        }
    ]
}

queryset = SaleLineItem.objects.all()
serializer_class = SaleLineItemSerializer
authentication_classes = [PosGatewayAuthentication, WebSessionAuthentication]
permission_classes = [IsAuthenticated]
filter_backends = [DjangoFilterBackend, filters.SearchFilter, filters.OrderingFilter]
search_fields = ['skuSnapshot', 'nameSnapshot', 'transaction__transactionId']
ordering_fields = ['created_at', 'unitPrice', 'quantity']
ordering = ['-created_at']

class SaleLineItemFilter(django_filters.FilterSet):
    transaction_id = django_filters.CharFilter(
        field_name='transaction__transactionId',
        lookup_expr='icontains'
    )
    sku = django_filters.CharFilter(
        field_name='skuSnapshot',
        lookup_expr='icontains'
    )
    product_name = django_filters.CharFilter(
        field_name='nameSnapshot',
        lookup_expr='icontains'
    )
    min_quantity = django_filters.NumberFilter(field_name='quantity', lookup_expr='gte')
    max_quantity = django_filters.NumberFilter(field_name='quantity', lookup_expr='lte')
    min_price = django_filters.NumberFilter(field_name='unitPrice', lookup_expr='gte')
    max_price = django_filters.NumberFilter(field_name='unitPrice', lookup_expr='lte')
    date_from = django_filters.DateTimeFilter(field_name='created_at', lookup_expr='gte')
    date_to = django_filters.DateTimeFilter(field_name='created_at', lookup_expr='lte')

def get_queryset(self):
    """Optimize queryset with select_related."""
    return SaleLineItem.objects.select_related(
        'transaction',
        'transaction__store',
        'productVariant',
        'productVariant__product'
    )

GET /sale-line-items/by_transaction/?transaction_id=TXN-20251117-A3B4C5D6

GET /sale-line-items/by_product/?variant_id=uuid-here

queryset = Return.objects.all()
serializer_class = ReturnSerializer
authentication_classes = [PosGatewayAuthentication, WebSessionAuthentication]
permission_classes = [IsAuthenticated]
filter_backends = [DjangoFilterBackend, filters.SearchFilter, filters.OrderingFilter]
search_fields = ['returnId', 'reason', 'originalSaleId__transactionId']
ordering_fields = ['created_at', 'status', 'returnId']
ordering = ['-created_at']

class ReturnFilter(django_filters.FilterSet):
    original_transaction_id = django_filters.CharFilter(
        field_name='originalSaleId__transactionId',
        lookup_expr='icontains'
    )
    status = django_filters.ChoiceFilter(choices=Return.Status.choices)
    date_from = django_filters.DateTimeFilter(field_name='created_at', lookup_expr='gte')
    date_to = django_filters.DateTimeFilter(field_name='created_at', lookup_expr='lte')
    employee = django_filters.NumberFilter(field_name='employeeId')

def get_queryset(self):
    """Optimize queryset with select_related."""
    return Return.objects.select_related(
        'originalSaleId',
        'originalSaleId__store',
        'employeeId',
        'processedBy'
    ).prefetch_related('return_line_items', 'refunds')

{
    "original_transaction_id": "TXN-20251117-A3B4C5D6",
    "return_items": [
        {
            "transaction_item_id": "line-item-uuid",
            "quantity": 2,
            "reason": "changed_mind",
            "disposition": "sellable"
        }
    ],
    "reason": "Customer changed their mind",
    "refund_method": "original",
    "refund_to_payment_ids": ["payment-uuid"]
}

required_fields = ['original_transaction_id', 'return_items', 'reason', 'refund_method']
for field in required_fields:
    if field not in request.data:
        return Response({'error': f'Missing required field: {field}'}, status=400)

original_transaction = SaleTransaction.objects.get(
    transactionId=request.data['original_transaction_id']
)

employee = request.user  # Use authenticated user directly (POS terminals)

return_service = ReturnService()

# Handle both single payment ID (legacy) and multiple payment IDs
refund_to_payment_ids = request.data.get('refund_to_payment_ids')
if not refund_to_payment_ids and request.data.get('refund_to_payment_id'):
    refund_to_payment_ids = [request.data.get('refund_to_payment_id')]

return_record = return_service.process_return(
    original_transaction=original_transaction,
    return_items_data=request.data['return_items'],
    reason=request.data['reason'],
    employee=employee,
    refund_method=request.data['refund_method'],
    refund_to_payment_ids=refund_to_payment_ids
)

{
    "transaction_id": "TXN-20251117-A3B4C5D6"
}

{
    "transaction_id": "TXN-20251117-A3B4C5D6",
    "status": "partially_refunded",
    "message": "Return started successfully"
}

{
    "transaction_id": "TXN-20251117-A3B4C5D6"
}

{
    "transaction_id": "TXN-20251117-A3B4C5D6",
    "status": "completed",
    "message": "Return cancelled successfully"
}

{
    "return_id": "RET-20251117-F7E8D9C0",
    "original_transaction": "TXN-20251117-A3B4C5D6",
    "status": "processed",
    "reason": "Customer changed their mind",
    "created_at": "2025-11-17T10:30:00Z",
    "employee": "John Doe",
    "processed_by": "Jane Manager",
    "customer": "Alice Smith",
    "items": [
        {
            "product_name": "Widget Pro",
            "sku": "WIDG-001",
            "quantity": 2,
            "return_price": "29.99",
            "reason": "changed_mind",
            "disposition": "sellable"
        }
    ],
    "refunds": [
        {
            "refund_id": "REF-20251117-C1D2E3F4",
            "amount": "59.98",
            "status": "succeeded",
            "processed_at": "2025-11-17T10:35:00Z",
            "payment_method": "Credit Card"
        }
    ],
    "totals": {
        "items_count": 2,
        "total_return_value": "59.98",
        "total_refund_amount": "59.98"
    }
}

queryset = ReturnLineItem.objects.all()
serializer_class = ReturnLineItemSerializer
authentication_classes = [PosGatewayAuthentication, WebSessionAuthentication]
permission_classes = [IsAuthenticated]
filter_backends = [DjangoFilterBackend, filters.SearchFilter, filters.OrderingFilter]
search_fields = ['skuSnapshot', 'nameSnapshot', 'sales_return__returnId']
ordering_fields = ['created_at', 'returnPrice', 'quantity']
ordering = ['-created_at']

class ReturnLineItemFilter(django_filters.FilterSet):
    sales_return = django_filters.UUIDFilter(field_name='sales_return__id')
    return_id = django_filters.CharFilter(
        field_name='sales_return__returnId',
        lookup_expr='icontains'
    )
    reason = django_filters.ChoiceFilter(choices=ReturnLineItem.ReturnReason.choices)
    disposition = django_filters.ChoiceFilter(choices=ReturnLineItem.Disposition.choices)
    date_from = django_filters.DateTimeFilter(field_name='created_at', lookup_expr='gte')
    date_to = django_filters.DateTimeFilter(field_name='created_at', lookup_expr='lte')

def get_queryset(self):
    """Optimize queryset with select_related."""
    return ReturnLineItem.objects.select_related(
        'sales_return',
        'sales_return__originalSaleId',
        'original_sale_line_item',
        'original_sale_line_item__productVariant'
    ).prefetch_related('reference_inventory_levels')

serializer_class = FulfillmentSerializer
authentication_classes = [WebSessionAuthentication, CustomTokenAuthentication]
permission_classes = [AllowAny]
lookup_field = 'id'

def get_queryset(self):
    user = self.request.user

    if user.is_authenticated:
        # Authenticated user: return all their fulfillments
        customer_profiles = user.customer_roles.all()
        if customer_profiles.exists():
            return queryset.filter(transaction__customer__in=customer_profiles)
        return Fulfillment.objects.none()

    # Guest user: check for web session
    web_session = self.request.auth
    if web_session and hasattr(web_session, 'get'):
        checkout_session_id = self.request.session.get('checkout_session_id')
        if checkout_session_id:
            return queryset.filter(transaction__sourceCheckoutId=checkout_session_id)

    return Fulfillment.objects.none()

{
    "count": 5,
    "results": [
        {
            "id": "uuid-here",
            "customer_email": "[email protected]",
            "status": "shipped",
            "shipping_city": "Denver",
            "total_amount": "129.99",
            "shipments": [
                {
                    "carrier_name": "UPS",
                    "tracking_number": "1Z999AA10123456784",
                    "status": "in_transit",
                    "items": [
                        {
                            "sku": "WIDG-001",
                            "name": "Widget Pro",
                            "quantity_shipped": 2
                        }
                    ]
                }
            ]
        }
    ]
}

serializer_class = ShipmentSerializer
authentication_classes = [WebSessionAuthentication, CustomTokenAuthentication]
permission_classes = [AllowAny]
lookup_field = 'id'

{
    "id": "uuid-here",
    "carrier_name": "UPS",
    "tracking_number": "1Z999AA10123456784",
    "status": "in_transit",
    "status_display": "In Transit",
    "shipped_at": "2025-12-07T14:30:00Z",
    "delivered_at": null,
    "items": [
        {
            "id": 1,
            "line_item_id": "uuid-here",
            "quantity_shipped": 2,
            "sku": "WIDG-001",
            "name": "Widget Pro"
        }
    ],
    "total_items": 2,
    "created_at": "2025-12-07T10:00:00Z",
    "updated_at": "2025-12-07T14:30:00Z"
}

queryset = PaymentMethod.objects.filter(is_active=True)
serializer_class = PaymentMethodSerializer

def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)
    self.payment_service = PaymentService()

@action(detail=False, methods=['get'])
@handle_view_exception
def available(self, request):
    """Get available payment methods with validation delegated."""
    serializer = AvailablePaymentMethodsSerializer(data=request.query_params)
    serializer.is_valid(raise_exception=True)
    validated_data = serializer.validated_data
    try:
        methods = self.payment_service.get_available_payment_methods(
            transaction_type=validated_data['type'], amount=validated_data.get('amount')
        )
        response_serializer = self.get_serializer(methods, many=True)
        return Response(response_serializer.data, status=status.HTTP_200_OK)
    except Exception as e:
        logger.error(f"Get available payment methods failed: {str(e)}")
        raise BusinessLogicException("Failed to get available payment methods")

GET /payment-methods/available/?type=pos&amount=59.99

{
    "store_id": "uuid-here",
    "register_id": "REG-001",
    "shift_id": "SHIFT-001",
    "starting_amount": "200.00"
}

{
    "store_id": "uuid-here",
    "register_id": "REG-001",
    "shift_id": "SHIFT-001",
    "ending_amount": "450.00",
    "cash_breakdown": {
        "hundreds": 4,
        "twenties": 2,
        "tens": 5,
        "fives": 0,
        "ones": 0
    }
}

if abs(result.get('variance', 0)) > Decimal('10.00'):
    SecurityEventLogger.log_suspicious_activity(
        'cash_drawer_variance', f"Significant cash variance: \${result['variance']}",
        request, 'warning', {'variance': str(result['variance'])}
    )

{
    "event": { /* CashDrawerEvent */ },
    "variance": "-5.00",  // Expected vs counted
    "expected_amount": "455.00"
}

{
    "store_id": "uuid-here",
    "register_id": "REG-001",
    "amount": "100.00",
    "reason": "Change fund replenishment",
    "notes": "From safe"
}

{
    "store_id": "uuid-here",
    "register_id": "REG-001",
    "amount": "50.00",
    "reason": "Vendor payment",
    "notes": "Office supplies"
}

GET /cash-drawer/status/?store_id=uuid-here&register_id=REG-001

{
    "is_open": true,
    "current_amount": "325.00",
    "opened_at": "2025-11-17T09:00:00Z",
    "opened_by": "John Doe",
    "transactions_count": 12,
    "last_event": "sale"
}

{
    "store_id": "uuid-here",
    "register_id": "REG-001",
    "counted_amount": "325.00",
    "cash_breakdown": {
        "hundreds": 3,
        "twenties": 1,
        "fives": 1
    },
    "notes": "Mid-shift count"
}

permission_classes = [AllowAny]

def get(self, request):
    if not settings.DEBUG:
        return Response({'error': 'This endpoint is only available in development mode'},
                      status=status.HTTP_404_NOT_FOUND)

    transactions = SaleTransaction.objects.all().order_by('-created_at')[:20]
    serializer = SaleTransactionSerializer(transactions, many=True)

    return Response({
        'count': transactions.count(),
        'results': serializer.data,
        'message': 'Development view - showing latest 20 transactions'
    })