Invoices API

Create, retrieve, and manage invoices with line items, merchant details, QR code generation, and payment tracking.

Base:/v1/invoice

Endpoints

GET

/v1/invoice/getByReference(code='{code}')

Public

Get Invoice by Reference Code

Retrieve an invoice by its public reference code. This is a public endpoint that does not require authentication, used for payment links.

Path Parameters

Name	Type	Required	Description
code	string	Required	Invoice reference code

Query Parameters

Name	Type	Required	Description
$expand	string	Optional	Related entities to include. Default: Merchant($expand=Media),SourceInfo,DestinationInfo,Items,MerchantLocation($expand=Address)

Response

{
  "id": 100,
  "identifier": "abc-123-def",
  "referenceNumber": "REF-001",
  "invoiceNumber": "INV-2024-001",
  "description": "Monthly subscription",
  "status": "Pending",
  "totalDue": 150.00,
  "totalPaid": 0,
  "subTotal": 140.00,
  "taxAmount": 10.00,
  "totalCost": 150.00,
  "currencyCode": "USD",
  "validFrom": "2024-03-01T00:00:00Z",
  "validTo": "2024-03-31T23:59:59Z",
  "paymentDueDate": "2024-03-15T00:00:00Z",
  "merchant": {
    "id": 1,
    "name": "Acme Corp",
    "email": "[email protected]",
    "media": [{ "mediaUrl": "https://..." }]
  },
  "items": [
    {
      "id": 1,
      "name": "Pro Plan",
      "description": "Monthly subscription",
      "unitCost": 140.00,
      "quantity": 1,
      "taxRate": 7.14,
      "taxAmount": 10.00,
      "totalCost": 150.00,
      "invoiceItemTypeId": "Subscription"
    }
  ],
  "sourceInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]"
  }
}

GET

/v1/invoice/{id}

Get Invoice by ID

Retrieve a specific invoice by its ID. Requires authentication.

Path Parameters

Name	Type	Required	Description
id	number	Required	Invoice ID

Query Parameters

Name	Type	Required	Description
$expand	string	Optional	Related entities to expand

GET

/v1/invoice/{id}/PaymentMethods

Get Invoice Payment Methods

Retrieve available payment methods configured for a specific invoice.

Path Parameters

Name	Type	Required	Description
id	number	Required	Invoice ID

Response

{
  "value": [
    {
      "id": 1,
      "code": "VISA",
      "name": "Visa Credit Card",
      "paymentMethodId": "CreditCard",
      "isEnabled": true,
      "currencyCode": "USD"
    }
  ]
}

GET

/v1/invoice/qrcode/{identifier}

Public

Get Invoice QR Code

Generate a QR code image for an invoice payment link.

Path Parameters

Name	Type	Required	Description
identifier	string	Required	Invoice identifier (UUID)

Response

// Returns image/png binary data

Returns a PNG image directly. Use as an image src URL.

GET

/v1/invoice

List Invoices

Retrieve a paginated list of invoices with OData filtering and sorting.

Query Parameters

Name	Type	Required	Description
$filter	string	Optional	OData filter. e.g. status eq 'Pending'
$orderby	string	Optional	Sort order. e.g. 'createdDateTime desc'
$top	number	Optional	Page size
$skip	number	Optional	Offset for pagination
$expand	string	Optional	Related entities to include
$select	string	Optional	Fields to select

Enums

InvoiceStatus

Draft

Pending

Sent

PartiallyPaid

Paid

Overdue

Cancelled

Expired

InvoiceItemType

Product

Service

Subscription

Fee

Discount

Tax

Types

InvoiceDto

interface InvoiceDto {
  id: number;
  identifier: string;              // UUID for public links
  referenceNumber?: string;
  invoiceNumber?: string;
  description?: string;
  merchant?: MerchantDto;
  merchantLocation?: MerchantLocationDto;
  status: InvoiceStatus;
  totalDue?: number;
  totalPaid?: number;
  subTotal?: number;
  taxRate?: number;
  taxAmount?: number;
  totalCost: number;
  discount?: number;
  shippingCost?: number;
  currencyCode: string;
  validFrom?: string;
  validTo?: string;
  paymentDueDate?: string;
  items?: InvoiceItemDto[];
  sourceInfo?: CounterPartyInfoDto;     // Payer
  destinationInfo?: CounterPartyInfoDto; // Payee
  notes?: string;
  cancelUrl?: string;              // Redirect on cancel
  successUrl?: string;             // Redirect on success
}

InvoiceItemDto

interface InvoiceItemDto {
  id?: number;
  itemIdentifier?: string;
  name: string;
  description?: string;
  unitCost: number;
  quantity: number;
  discount?: number;
  taxRate?: number;
  taxAmount?: number;
  subTotal?: number;
  totalCost?: number;
  shippingCost?: number;
  currencyCode?: string;
  invoiceItemTypeId?: InvoiceItemType;
}

Usage Examples

Fetch invoice for payment page

TypeScript

import { invoiceApi, canInvoiceBePaid, formatCurrency } from '@/lib/api/ecommerce-client';

// Public access — no auth required
const invoice = await invoiceApi.getByReference('INV-2024-001');

if (canInvoiceBePaid(invoice)) {
  const methods = await invoiceApi.getPaymentMethods(invoice.id);
  console.log(`Amount due: ${formatCurrency(invoice.totalCost, invoice.currencyCode)}`);
  console.log(`Payment methods: ${methods.map(m => m.name).join(', ')}`);
}

Display QR code for invoice

TypeScript

import { invoiceApi } from '@/lib/api/ecommerce-client';

function InvoiceQrCode({ identifier }: { identifier: string }) {
  const qrUrl = invoiceApi.getQrCodeUrl(identifier);

  return (
    <img
      src={qrUrl}
      alt="Scan to pay"
      className="h-48 w-48"
    />
  );
}

List invoices with OData filtering

TypeScript

import { apiClient } from '@/lib/api/client';
import { buildODataQuery } from '@/lib/api/endpoints';

const query = buildODataQuery({
  filter: "status eq 'Pending'",
  orderBy: 'createdDateTime desc',
  top: 20,
  skip: 0,
  expand: ['Merchant', 'Items'],
});

const { data } = await apiClient.get(`/v1/invoice${query}`);

Real-time invoice updates via SignalR

TypeScript

import { useSignalR } from '@/hooks/use-signalr';
import { HUB_EVENTS } from '@/lib/signalr/types';

function InvoiceMonitor() {
  useSignalR('/hubs/notifications', {
    [HUB_EVENTS.InvoiceUpdated]: (notification) => {
      console.log(`Invoice ${notification.invoiceId} → ${notification.status}`);
      // Refresh invoice data
      queryClient.invalidateQueries({ queryKey: ['invoices'] });
    },
  });
}

Helpers

canInvoiceBePaid()

TypeScript

// Returns false for: Paid, Expired, Draft, Cancelled
// Returns true for: Pending, Sent, PartiallyPaid, Overdue
import { canInvoiceBePaid } from '@/lib/api/ecommerce-client';

const canPay = canInvoiceBePaid(invoice); // boolean