Skip to main content

ls-invoices Web Component

Overview​

The ls-invoices web component provides a comprehensive invoice management interface for customers within the APEX platform. Built using Lit Element, this component displays customer invoices in a responsive, user-friendly format with features for emailing invoices and viewing detailed itemized billing information.

Prerequisites​

  • Modern web browser with ES6+ support
  • Access to the APEX platform CDN
  • Valid API subscription key for billing services
  • Proper user authentication and authorization

Configuration​

To use the ls-invoices component

Component Loading​

<!-- Load the component from CDN -->
<script src="https://cdn.platform.coaxle.co.za/billing/scripts/ls-invoices.js"></script>

Basic Usage​

<ls-invoices currency-symbol="R"></ls-invoices>

API Reference​

Properties​

currencySymbol​

  • Type: string
  • Default: 'R'
  • Description: The currency symbol to display with invoice amounts
<ls-invoices currency-symbol="R"></ls-invoices>

accountId​

  • Type: string | undefined
  • Default: undefined
  • Description: When provided, filters invoices to show only those for the specified account. If not provided, the component displays all invoices for the authenticated user.
<!-- Show invoices for specific account -->
<ls-invoices account-id="ACC-12345"></ls-invoices>

<!-- Show all invoices for authenticated user -->
<ls-invoices></ls-invoices>

Behavior:

  • With accountId: Calls the /Finance/GetInvoicesForAccount/{accountId} API endpoint
  • Without accountId: Calls the /Finance/GetInvoices API endpoint

Methods​

invoiceClicked(invoice: Invoice)​

Handles the "Email invoice" button click event. Sends the invoice via email to the customer.

Parameters:

  • invoice (Invoice): The invoice object to be emailed

Usage: This method is called automatically when users click the "Email invoice" button. It triggers the email sending process through the Finance API.

itemizedBilling(invoice: Invoice)​

Opens the itemized billing modal for detailed invoice breakdown.

Parameters:

  • invoice (Invoice): The invoice object to display detailed billing for

Usage: This method is called automatically when users click the "View Itemized Billing" button. It loads the itemized billing component dynamically.

closeMessage()​

Closes success or error messages displayed to the user.

Usage: Called automatically when users click the 'x' button on alert messages.

Data Models​

Invoice Interface​

interface Invoice {
  invoiceDate: Date;      // The date the invoice was created
  invoiceNumber: string;  // Unique invoice identifier
  amount: number;         // Total invoice amount
  outstanding: number;    // Outstanding amount (if applicable)
  invoiceId: string;      // System invoice ID
}

Examples​

Basic Implementation​

<!DOCTYPE html>
<html>
<head>
    <title>Customer Invoices</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>
    <div class="container mt-4">
        <h1>Your Invoices</h1>
       
        <!-- Load and use component -->
        <script src="https://cdn.platform.coaxle.co.za/billing/scripts/ls-invoices.js"></script>
        <ls-invoices currency-symbol="R"></ls-invoices>
    </div>
</body>
</html>

Component States​

Loading State​

When the component is loading invoices, it displays a spinner:

<span class="ls-loader"></span>

Error States​

Unauthorized Access​

When a user doesn't have permission to view invoices:

<div class="alert alert-danger">
  <h4 class="alert-heading">Unauthorized</h4>
  You don't have access to view invoices. Please contact your administrator to request access.
</div>

General Error​

When there's a system error retrieving invoices:

<div class="alert alert-danger">
  Unfortunately we were unable to get any invoice details. Please try again later.
</div>

No Invoices​

When no invoices are found for the user/account:

No invoices

Success States​

Invoice Emailed Successfully​

When an invoice is successfully emailed:

<div class="alert alert-success">
  <button type="button" class="close">x</button>
  Invoice has been successfully emailed.
</div>

Styling and Customization​

CSS Custom Properties​

The component supports CSS custom properties for styling:

ls-invoices {
  --ls-invoices-text-color: #333;
}

Bootstrap Dependency​

The component relies on Bootstrap classes for styling. Ensure Bootstrap CSS is loaded:

<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet">

Custom Styling​

You can override component styles using CSS:

ls-invoices {
  padding: 20px;
  background-color: #f8f9fa;
}

ls-invoices .invoice {
  border-radius: 8px;
  margin-bottom: 10px;
}

ls-invoices .alert {
  border-radius: 4px;
}

Best Practices​

Security​

  • Always validate API keys and authentication tokens
  • Use HTTPS for all API communications
  • Implement proper error handling for unauthorized access
  • Don't store sensitive information in client-side code

Performance​

  • Use account-specific views when possible by providing the account-id attribute to reduce data load and improve response times
  • Implement proper loading states for better user experience
  • Consider pagination for accounts with many invoices
  • Cache API responses appropriately

User Experience​

  • Provide clear error messages for different failure scenarios
  • Use consistent currency symbols across your application
  • Include loading indicators during API calls
  • Make buttons and links clearly identifiable

Integration​

  • Configure environment variables before loading the component
  • Test component behavior in different authentication states
  • Ensure proper cleanup of event listeners if dynamically adding/removing components
  • Follow APEX platform authentication patterns

Common Issues and Solutions​

Issue: Component doesn't load​

Solution: Verify that the CDN URL is accessible and the script loads without errors

Issue: No invoices displayed despite having data​

Solution: Check API configuration, authentication, and network connectivity. Also verify if you need to provide an account-id attribute for account-specific invoice filtering

Issue: "Unauthorized" error message​

Solution: Verify user permissions and API key validity

Issue: Currency symbols not displaying correctly​

Solution: Ensure proper character encoding (UTF-8) and verify the currency-symbol attribute

Issue: Itemized billing modal doesn't open​

Solution: Check that the itemized-billing component script is accessible from the CDN

Issue: Email functionality not working​

Solution: Verify the Finance API endpoint is configured correctly and accessible

API Dependencies​

The component relies on these Finance API endpoints:

  • GET /Finance/GetInvoices - Retrieves all invoices for the authenticated user
  • GET /Finance/GetInvoicesForAccount/{accountId} - Retrieves invoices for a specific account
  • POST /Finance/SendInvoice/{invoiceNumber} - Sends an invoice via email

Browser Support​

The component supports modern browsers with ES6+ capabilities:

  • Chrome 61+
  • Firefox 60+
  • Safari 10.1+
  • Edge 79+

For older browser support, consider using polyfills for:

  • Custom Elements
  • ES6 Classes
  • Fetch API
  • Promise
  • itemized-billing - Dynamically loaded component for detailed invoice breakdowns
  • ls-onsell - Component for invoice viewing and download functionality (referenced in the invoice display)