Invoicing

Part ofFinOps↗

Lists, creates, edits and acts on an organization's invoices, including sending by email and recording payments.

Quick Start

import { ReceivablesWidget } from '@tesouro/embedded-components-react';

export function ReceivablesPage({ widgetToken }: { widgetToken: string }) {
  return (
    <ReceivablesWidget
      baseUrl="https://api.tesouro.com"
      widgetToken={widgetToken}
      organizationId="org_..."
    />
  );
}

The widget loads the first page once auth and organization scope resolve, and opens its own sheets and dialogs for details, create/edit, send and payment.

Behaviour

• This replaces the earlier InvoicingWidget, which took pageTitleComponent and finopsThemeColors. Neither exists now: pass your page title as headerStart.
• The widget handles invoices only: there are no quote or credit-note tabs, and create always makes an invoice.
• After a create succeeds, the widget calls onReceivableCreated. A duplicate does not call it, as in the legacy widget. A duplicate, draft or recurring series opens its details. Issuing an invoice doesn't: a follow-up modal offers to email it when the customer has an email address. After any create, the modal also offers to save typed items that aren't in the catalog as products.
• The list matches the Monite one: due date, status, number, customer, issue date and amount, with "Pending" for a number or date not yet set. It opens sorted by due date, newest first, and clearing a sort returns to that order. With no status picked, it hides canceled, recurring and failed invoices.
• Changing sort, page size, any filter or search returns to the first page.
• A filter bar offers search, plus a Filters menu for due date, created on and issue date ranges, multi-select status, amount (exact or range) and customer. Each applied filter shows as a dismissible chip, and Clear all removes every one.
• The widget renders no heading of its own. Pass your page title as headerStart, and the sponsor bank's logo as bankAttribution for the "Business Banking provided by" line beneath it. Both sit in a header row with the invoice settings button and "Create Invoice".
• The widget reads the widget token's scopes. Without invoice:read:org it shows an access-restricted state instead of the list. Without invoice:write:org it hides Create and the details panel's actions, so a read-only user can browse and open invoices but not change them. The invoice settings button needs organization_settings:write:org as well as a handler.
• The invoice form sets payment reminders (before the due date and overdue); issuing is blocked when the customer has reminders off or no email.

Props

Widget props

Each label prop is merged over the English defaults, so pass only the strings you want to change.

See the exported label types listed under TypeScript for every key.

Examples

With a page title and bank attribution

<ReceivablesWidget
  headerStart={<h1>Invoicing</h1>}
  bankAttribution={{ logoSrc: bankLogoUrl, logoAlt: `${bankName} logo` }}
  onTemplateSettingsClick={() => router.push('/settings/invoice')}
/>

Custom labels

<ReceivablesWidget
  screenLabels={{
    createInvoiceButton: 'New invoice',
    statusBadge: { issued: 'Sent', partially_paid: 'Part paid' },
  }}
  messageLabels={{ genericError: 'Unable to complete this action.' }}
/>

TypeScript

import type {
  ReceivablesWidgetProps,
  ReceivableDocumentType,
  ReceivablesScreenLabels,
  ReceivablesScreenLabelOverrides,
  ReceivableStatusBadgeLabels,
  InvoicesFilterBarLabelOverrides,
  InvoicesFilterLabelOverrides,
  ReceivableFormDialogLabels,
  ReceivablePreviewLabels,
  ReceivableDetailsPanelLabels,
  ReceivableDetailsPanelLabelOverrides,
  ReceivablePaymentDialogLabels,
  ReceivableActionDialogLabels,
  ReceivableActionsModalLabels,
  ReceivableBankAttribution,
  ReceivableMessageLabels,
  CounterpartFormSheetLabels,
  CounterpartMessageLabels,
  MeasureUnitsManagerLabels,
  MeasureUnitDeleteDialogLabels,
  ProductMessageLabels,
} from '@tesouro/embedded-components-react';