@zeniai/client-epic-state 5.2.41 → 5.2.42-betaAK0

package/lib/esm/view/expenseAutomationView/selectors/actualMatchingViewSelector.js

@@ -0,0 +1,426 @@
+import orderBy from 'lodash/orderBy';
+import { toMonthYearPeriodId, } from '../../../commonStateTypes/timePeriod';
+import { getActualMatchingMatchById } from '../../../entity/actualMatching/actualMatchingSelector';
+import { generateJEOneTimeAccrualKey } from '../../../entity/jeSchedules/jeScheduleHelper';
+import { getJEOneTimeAccrualByKey, } from '../../../entity/jeSchedules/jeSchedulesSelector';
+import { getCurrentTenant } from '../../../entity/tenant/tenantSelector';
+import { date } from '../../../zeniDayJS';
+import { actualMatchingTransactionLineKey, } from '../types/actualMatchingViewState';
+export function getSelectedMonthYearForCurrentTenant(state) {
+    const tenantId = getCurrentTenant(state)?.tenantId;
+    if (tenantId == null) {
+        return undefined;
+    }
+    return state.expenseAutomationViewState.selectedPeriodByTenantId[tenantId];
+}
+export function getTenantDisplayCurrency(state) {
+    const locale = getCurrentTenant(state)?.company?.companyLocaleInfo;
+    if (locale?.currencyCode == null || locale.currencyCode === '') {
+        return undefined;
+    }
+    return {
+        currencyCode: locale.currencyCode,
+        currencySymbol: locale.currencySymbol != null && locale.currencySymbol !== ''
+            ? locale.currencySymbol
+            : locale.currencyCode,
+    };
+}
+function toMatchModalAccrual(member) {
+    if ('jeOneTimeAccrualKey' in member && member.jeOneTimeAccrualKey != null) {
+        return member;
+    }
+    return {
+        ...member,
+        jeOneTimeAccrualKey: generateJEOneTimeAccrualKey(member.accrualId),
+    };
+}
+function uniqueMatchModalAccruals(pinned, searched) {
+    const byId = new Map();
+    pinned.forEach((row) => byId.set(row.accrualId, row));
+    searched.forEach((row) => {
+        if (!byId.has(row.accrualId)) {
+            byId.set(row.accrualId, row);
+        }
+    });
+    return Array.from(byId.values());
+}
+function uniqueTransactionSearchResults(pinned, searched) {
+    const byKey = new Map();
+    pinned.forEach((row) => byKey.set(actualMatchingTransactionLineKey(row.transactionType, row.transactionIntegrationId, row.lineId), row));
+    searched.forEach((row) => {
+        const key = actualMatchingTransactionLineKey(row.transactionType, row.transactionIntegrationId, row.lineId);
+        if (!byKey.has(key)) {
+            byKey.set(key, row);
+        }
+    });
+    return Array.from(byKey.values());
+}
+export function parseActualMatchingMatchId(matchId) {
+    const separator = matchId.indexOf(':');
+    if (separator <= 0 || separator === matchId.length - 1) {
+        return null;
+    }
+    return {
+        transactionType: matchId.slice(0, separator).toLowerCase(),
+        transactionIntegrationId: matchId.slice(separator + 1),
+    };
+}
+const NOT_STARTED = {
+    fetchState: 'Not-Started',
+    error: undefined,
+};
+export function isAutoReversedAccrual(accrual) {
+    return (accrual.accrualStatus === 'reversed' &&
+        accrual.reversalTrigger === 'bill_match');
+}
+export function isManuallyReversedAccrual(accrual) {
+    return (accrual.accrualStatus === 'reversed' &&
+        accrual.reversalTrigger === 'manual_reverse');
+}
+export function isPendingReviewAccrual(accrual) {
+    if (accrual.accrualStatus !== 'posted' || accrual.matchSuggestion == null) {
+        return false;
+    }
+    const resolution = accrual.matchSuggestion.resolution;
+    return resolution == null || resolution.length === 0;
+}
+export function isReversedMatchKind(kind) {
+    return kind === 'auto_reversed' || kind === 'manually_reversed';
+}
+export function getClearedMatchedAmount(accrual) {
+    return accrual.cleared?.matchedAmount?.amount;
+}
+export function getActualMatchingAmount(row) {
+    return row.actualAmount?.amount ?? row.estimatedAmount.amount;
+}
+function parseMatchTransactionDate(transactionDate) {
+    if (transactionDate == null || transactionDate === '') {
+        return undefined;
+    }
+    const parsed = date(transactionDate);
+    return Number.isFinite(parsed.valueOf()) ? parsed : undefined;
+}
+export function getActualMatchingReversalDate(accrual, matchTransactionDate) {
+    const matchedDate = isPendingReviewAccrual(accrual)
+        ? accrual.matchSuggestion.matchedTransactionDate
+        : accrual.cleared?.matchedTransactionDate;
+    return matchedDate ?? parseMatchTransactionDate(matchTransactionDate);
+}
+function collectGroupedMembers(members) {
+    if (members.length <= 1) {
+        return undefined;
+    }
+    return members.map((member) => ({
+        accrualId: member.accrualId,
+        estimatedAmount: member.estimatedAmount,
+        jeDebitAccountName: member.jeDebitAccountName,
+        memo: member.memo,
+        serviceMonth: member.serviceMonth,
+    }));
+}
+function collectLeftoverMembers(leftovers) {
+    if (leftovers == null || leftovers.length === 0) {
+        return undefined;
+    }
+    return leftovers.map((member) => ({
+        accrualId: member.accrualId,
+        estimatedAmount: member.estimatedAmount,
+        jeDebitAccountName: member.jeDebitAccountName,
+        memo: member.memo,
+        serviceMonth: member.serviceMonth,
+    }));
+}
+function toActualMatchingRow(match) {
+    const firstMember = match.members[0];
+    if (firstMember == null) {
+        throw new Error('Actual matching row requires at least one member');
+    }
+    const first = toMatchModalAccrual(firstMember);
+    const leftoverMembers = match.leftovers ?? [];
+    const fromCleared = firstMember.cleared?.intendedAccrualIds;
+    const intendedAccrualIds = fromCleared != null && fromCleared.length > 0
+        ? fromCleared
+        : [
+            ...match.members.map((member) => member.accrualId),
+            ...leftoverMembers.map((leftover) => leftover.accrualId),
+        ];
+    return {
+        ...first,
+        matchId: match.matchId,
+        kind: match.kind,
+        accruedAmount: match.accruedAmount,
+        actualAmount: match.actualAmount,
+        matchTier: match.matchTier,
+        matchShape: match.matchShape,
+        transactionType: match.transactionType,
+        transactionDate: match.transactionDate,
+        groupedAccrualIds: match.members.map((member) => member.accrualId),
+        groupedMembers: collectGroupedMembers(match.members),
+        intendedAccrualIds,
+        leftovers: collectLeftoverMembers(match.leftovers),
+        reversalDate: getActualMatchingReversalDate(first, match.transactionDate),
+        vendorName: match.vendorName != null && match.vendorName !== ''
+            ? match.vendorName
+            : first.vendorName,
+        estimatedAmount: match.accruedAmount,
+    };
+}
+function matchesSearch(row, searchString) {
+    const trimmed = searchString.trim().toLowerCase();
+    if (trimmed.length === 0) {
+        return true;
+    }
+    if ((row.vendorName ?? '').toLowerCase().includes(trimmed)) {
+        return true;
+    }
+    if ((row.memo ?? '').toLowerCase().includes(trimmed)) {
+        return true;
+    }
+    return (row.groupedMembers ?? []).some((member) => (member.memo ?? '').toLowerCase().includes(trimmed));
+}
+function getActualMatchingSortValue(row, sortKey) {
+    switch (sortKey) {
+        case 'vendor':
+            return (row.vendorName ?? '').toLowerCase();
+        case 'date': {
+            const millis = row.reversalDate?.valueOf() ??
+                (row.transactionDate != null && row.transactionDate !== ''
+                    ? date(row.transactionDate).valueOf()
+                    : 0);
+            return Number.isFinite(millis) ? millis : 0;
+        }
+        case 'amount':
+            return getActualMatchingAmount(row);
+        case 'category':
+            return row.jeDebitAccountName?.toLowerCase();
+        case 'class':
+            return row.jeDebitAccountingClassName?.toLowerCase();
+        case 'type':
+            return row.transactionType?.toLowerCase();
+        case 'lifecycle':
+            return row.kind;
+        case 'service':
+            return row.serviceMonth;
+        case 'accrued':
+            return row.accruedAmount?.amount ?? row.estimatedAmount.amount;
+        case 'actual':
+            return row.actualAmount?.amount;
+        case 'variance': {
+            const accrued = row.accruedAmount?.amount ?? row.estimatedAmount.amount;
+            const actual = row.actualAmount?.amount;
+            if (actual == null || accrued === 0) {
+                return undefined;
+            }
+            return ((actual - accrued) / Math.abs(accrued)) * 100;
+        }
+        default:
+            return undefined;
+    }
+}
+function sortActualMatchingRows(rows, uiState) {
+    const lodashOrder = uiState.sortOrder === 'ascending' ? 'asc' : 'desc';
+    return orderBy(rows, [(row) => getActualMatchingSortValue(row, uiState.sortKey)], [lodashOrder]);
+}
+const ESTIMATED_MINUTES_PER_PENDING_MATCH = 4;
+function emptyKpiSummary() {
+    return {
+        actualsReceived: { count: 0, expectedCount: 0, vendorsPending: 0 },
+        autoReversed: { count: 0, percent: 0, clearedAmount: 0 },
+        pendingReview: { count: 0, amount: 0, estimatedMinutesToClear: 0 },
+        variance: { percent: 0, averagePercentPerMatch: 0, netAmount: 0 },
+    };
+}
+function sumRowAmounts(rows, displayCurrencyCode) {
+    return rows.reduce((sum, row) => {
+        if (displayCurrencyCode != null &&
+            row.accruedAmount.currencyCode !== displayCurrencyCode) {
+            return sum;
+        }
+        return sum + getActualMatchingAmount(row);
+    }, 0);
+}
+function isKnownKpiKind(kind) {
+    return (kind === 'auto_reversed' ||
+        kind === 'pending_review' ||
+        kind === 'manually_reversed');
+}
+function rowMatchesDisplayCurrency(row, displayCurrencyCode) {
+    if (displayCurrencyCode == null) {
+        return true;
+    }
+    const rowCurrency = row.accruedAmount?.currencyCode ?? row.estimatedAmount.currencyCode;
+    return rowCurrency === displayCurrencyCode;
+}
+function uniqueVendorCount(rows) {
+    const ids = new Set();
+    rows.forEach((row) => {
+        if (row.vendorId != null && row.vendorId !== '') {
+            ids.add(row.vendorId);
+            return;
+        }
+        if (row.vendorName != null && row.vendorName !== '') {
+            ids.add(row.vendorName);
+        }
+    });
+    return ids.size;
+}
+function rowVariancePercent(row) {
+    const accrued = row.accruedAmount?.amount ?? row.estimatedAmount.amount;
+    const actual = row.actualAmount?.amount;
+    if (actual == null || accrued === 0) {
+        return undefined;
+    }
+    return ((actual - accrued) / Math.abs(accrued)) * 100;
+}
+export function buildActualMatchingKpiSummary(rows, displayCurrencyCode) {
+    // Strip counts and amounts share this set: known kinds only, and (when a
+    // display currency is set) that currency only. Lists still render every row.
+    const kpiRows = rows.filter((row) => isKnownKpiKind(row.kind) &&
+        rowMatchesDisplayCurrency(row, displayCurrencyCode));
+    if (kpiRows.length === 0) {
+        return emptyKpiSummary();
+    }
+    const autoReversed = kpiRows.filter((row) => row.kind === 'auto_reversed');
+    const pendingReview = kpiRows.filter((row) => row.kind === 'pending_review');
+    const receivedCount = kpiRows.length;
+    const rowsWithActual = kpiRows.filter((row) => row.actualAmount?.amount != null);
+    const accruedTotal = rowsWithActual.reduce((sum, row) => sum + (row.accruedAmount?.amount ?? row.estimatedAmount.amount), 0);
+    const actualTotal = rowsWithActual.reduce((sum, row) => sum + (row.actualAmount?.amount ?? 0), 0);
+    const variancePercents = kpiRows
+        .map(rowVariancePercent)
+        .filter((percent) => percent != null);
+    return {
+        actualsReceived: {
+            count: receivedCount,
+            // List API does not return still-expected accruals; hide "of N expected"
+            // in the strip until expectedCount is greater than received.
+            expectedCount: receivedCount,
+            vendorsPending: uniqueVendorCount(pendingReview),
+        },
+        autoReversed: {
+            count: autoReversed.length,
+            percent: Math.round((autoReversed.length / receivedCount) * 100),
+            clearedAmount: sumRowAmounts(autoReversed, displayCurrencyCode),
+        },
+        pendingReview: {
+            count: pendingReview.length,
+            amount: sumRowAmounts(pendingReview, displayCurrencyCode),
+            estimatedMinutesToClear: pendingReview.length * ESTIMATED_MINUTES_PER_PENDING_MATCH,
+        },
+        variance: {
+            percent: accruedTotal === 0
+                ? 0
+                : ((actualTotal - accruedTotal) / Math.abs(accruedTotal)) * 100,
+            averagePercentPerMatch: variancePercents.length === 0
+                ? 0
+                : variancePercents.reduce((sum, percent) => sum + percent, 0) /
+                    variancePercents.length,
+            netAmount: actualTotal - accruedTotal,
+        },
+    };
+}
+export function getExpenseAutomationActualMatchingMatchView(state, matchId) {
+    const view = state.expenseAutomationActualMatchingViewState;
+    return {
+        match: getActualMatchingMatchById(state.actualMatchingState, matchId),
+        detailFetchState: view.detailFetchStateByMatchId[matchId] ?? NOT_STARTED,
+        refreshStatus: view.detailRefreshStatusByMatchId[matchId] ?? NOT_STARTED,
+        undoReversalStatus: view.undoReversalStatusByMatchId[matchId] ?? NOT_STARTED,
+        lastMatchResults: view.lastMatchResultsByMatchId?.[matchId],
+        lastUndoResults: view.lastUndoResultsByMatchId?.[matchId],
+    };
+}
+export function getCloseMatchAfterUndo(state) {
+    return state.expenseAutomationActualMatchingViewState.closeMatchAfterUndo;
+}
+export function getExpenseAutomationActualMatchingView(state) {
+    const { expenseAutomationActualMatchingViewState } = state;
+    const { matchIdsByPeriod, fetchState, error, refreshStatus, uiState, matchModal, } = expenseAutomationActualMatchingViewState;
+    const selectedPeriod = getSelectedMonthYearForCurrentTenant(state);
+    const monthYearPeriodId = selectedPeriod != null ? toMonthYearPeriodId(selectedPeriod) : undefined;
+    const matchIds = monthYearPeriodId != null ? matchIdsByPeriod[monthYearPeriodId] : undefined;
+    const allRows = (matchIds ?? [])
+        .map((matchId) => getActualMatchingMatchById(state.actualMatchingState, matchId))
+        .filter((match) => match != null)
+        .filter((match) => match.members.length > 0)
+        .map(toActualMatchingRow);
+    const rows = allRows.filter((row) => matchesSearch(row, uiState.searchString));
+    const reversed = sortActualMatchingRows(rows.filter((row) => isReversedMatchKind(row.kind)), uiState);
+    const pendingReview = sortActualMatchingRows(rows.filter((row) => row.kind === 'pending_review'), uiState);
+    const kpiSummary = buildActualMatchingKpiSummary(allRows, getTenantDisplayCurrency(state)?.currencyCode);
+    const searchedAccruals = matchModal.accrualSearch.results
+        .map((key) => getJEOneTimeAccrualByKey(key, state.jeSchedulesState))
+        .filter((accrual) => accrual != null);
+    const openedMatch = matchModal.openedFromMatchId != null
+        ? getActualMatchingMatchById(state.actualMatchingState, matchModal.openedFromMatchId)
+        : undefined;
+    const pinnedAccruals = [
+        ...(openedMatch?.members ?? []),
+        ...(openedMatch?.leftovers ?? []),
+    ].map(toMatchModalAccrual);
+    const firstMember = openedMatch?.members[0];
+    const cleared = firstMember?.cleared;
+    const suggestion = firstMember?.matchSuggestion;
+    const stamp = cleared ?? suggestion;
+    const consumedLineIds = cleared?.consumedLineIds;
+    const prefill = openedMatch == null
+        ? undefined
+        : {
+            selectedAccrualIds: [
+                ...openedMatch.members.map((member) => member.accrualId),
+                ...(openedMatch.leftovers ?? []).map((leftover) => leftover.accrualId),
+            ],
+            actualAmount: openedMatch.actualAmount.amount,
+            matchedTransactionId: stamp?.matchedTransactionId,
+            matchedLineId: cleared == null ? suggestion?.matchedLineId : undefined,
+            ...(consumedLineIds != null && consumedLineIds.length > 0
+                ? { consumedLineIds }
+                : {}),
+        };
+    // `fetchState` is a flat slice field that survives a period switch. Until this
+    // month's ids land, leftover Completed/Error is the previous month. Report
+    // Not-Started so chrome matches Review's "cache slot missing" skeleton, not
+    // empty-complete or a stale error. In-Progress is this month's fetch.
+    const fetchStatus = matchIds == null &&
+        fetchState !== 'In-Progress' &&
+        fetchState !== 'Not-Started'
+        ? { fetchState: 'Not-Started', error: undefined }
+        : { fetchState, error };
+    return {
+        fetchState: fetchStatus.fetchState,
+        error: fetchStatus.error,
+        reversed,
+        pendingReview,
+        kpiSummary,
+        uiState,
+        refreshStatus,
+        hasLoadedForSelectedPeriod: matchIds != null,
+        matchModal: {
+            isOpen: matchModal.isOpen,
+            openedFromMatchId: matchModal.openedFromMatchId,
+            prefill,
+            confirmStatus: matchModal.confirmStatus,
+            lastBatchResults: matchModal.lastBatchResults,
+            transactionSearch: {
+                query: matchModal.transactionSearch.query,
+                results: uniqueTransactionSearchResults(matchModal.pinnedTransactionResults, matchModal.transactionSearch.results),
+                fetchState: {
+                    fetchState: matchModal.transactionSearch.fetchState,
+                    error: matchModal.transactionSearch.error,
+                },
+                nextPageToken: matchModal.transactionSearch.nextPageToken,
+                isLoadingMore: matchModal.transactionSearch.isLoadingMore,
+            },
+            accrualSearch: {
+                query: matchModal.accrualSearch.query,
+                results: uniqueMatchModalAccruals(pinnedAccruals, searchedAccruals),
+                fetchState: {
+                    fetchState: matchModal.accrualSearch.fetchState,
+                    error: matchModal.accrualSearch.error,
+                },
+                nextPageToken: matchModal.accrualSearch.nextPageToken,
+                isLoadingMore: matchModal.accrualSearch.isLoadingMore,
+            },
+        },
+    };
+}

package/lib/esm/view/expenseAutomationView/selectors/jeSchedulesViewSelector.js

@@ -366,6 +366,10 @@ export function getExpenseAutomationJESchedulesView(state) {
     // reports undefined rather than 0, so the UI can hide the badge instead of asserting "none".
     const scheduleCountsByTab = {};
     ALL_JE_PAGE_TABS.forEach((pageTab) => {
+        // AM's badge is `actualMatching.kpiSummary`, not schedule row keys.
+        if (pageTab === 'actual_matching') {
+            return;
+        }
         const periodTabKey = monthYearPeriodId != null
             ? getJESchedulePeriodTabKey(pageTab, monthYearPeriodId)
             : null;

package/lib/esm/view/expenseAutomationView/types/actualMatchingViewState.js

@@ -0,0 +1,38 @@
+import { stringToUnion } from '../../../commonStateTypes/stringToUnion';
+const ACTUAL_MATCHING_SORT_KEYS = [
+    'vendor',
+    'date',
+    'amount',
+    'category',
+    'class',
+    'type',
+    'lifecycle',
+    'service',
+    'accrued',
+    'actual',
+    'variance',
+];
+export const toActualMatchingSortKey = (v) => stringToUnion(v, ACTUAL_MATCHING_SORT_KEYS);
+export const MATCH_TRANSACTION_SEARCH_PAGE_SIZE = 50;
+export const MATCH_ACCRUAL_SEARCH_LIMIT = 50;
+export const MATCH_SEARCH_DEBOUNCE_MS = 300;
+const MATCH_AND_REVERSE_RESULT_STATUSES = [
+    'reversed',
+    'noop',
+    'conflict',
+    'claim_lost',
+    'error',
+];
+export const toMatchAndReverseResultStatus = (v) => stringToUnion(v, MATCH_AND_REVERSE_RESULT_STATUSES);
+export function isMatchAndReverseCompleteStatus(status) {
+    return status === 'reversed' || status === 'noop';
+}
+const UNDO_REVERSAL_RESULT_STATUSES = [
+    'undone',
+    'claim_lost',
+    'error',
+];
+export const toUndoReversalResultStatus = (v) => stringToUnion(v, UNDO_REVERSAL_RESULT_STATUSES);
+export function actualMatchingTransactionLineKey(transactionType, transactionIntegrationId, lineId) {
+    return `${transactionType}:${transactionIntegrationId}:${lineId}`;
+}

package/lib/esm/view/expenseAutomationView/types/jeSchedulesViewState.js

@@ -16,7 +16,14 @@ const JE_SCHEDULE_SORT_KEYS = [
     'memo',
 ];
 export const toJEScheduleSortKey = (v) => stringToUnion(v, JE_SCHEDULE_SORT_KEYS);
-const JE_PAGE_TABS = ['schedules', 'existing_schedules'];
+// `actual_matching` is chrome only: the JE tab bar includes it, but AM data is
+// `expenseAutomationActualMatchingViewState`, not the schedules period-tab
+// cache below. Walks of ALL_JE_PAGE_TABS that read schedule keys must skip it.
+const JE_PAGE_TABS = [
+    'schedules',
+    'actual_matching',
+    'existing_schedules',
+];
 export const toJEPageTab = (v) => stringToUnion(v, JE_PAGE_TABS);
 export const ALL_JE_PAGE_TABS = JE_PAGE_TABS;
 export const getJESchedulePeriodTabKey = (selectedPageTab, monthYearPeriodId) => `${selectedPageTab}_${monthYearPeriodId}`;

package/lib/esm/view/invoicing/editInvoicingCatalogItemDetailView/editInvoicingCatalogItemDetailViewPayload.js

@@ -3,7 +3,6 @@ import { toClassBasePayload } from '../../../entity/class/classPayload';
 import { blankInvoicingCatalogSubFamily, isTieredCatalogPricingModel, } from './invoicingCatalogItemFormHelper';
 const CURRENCY_CODE = 'USD';
 const trimOrUndefined = (value) => value.trim() !== '' ? value.trim() : undefined;
-const trimOrNull = (value) => value.trim() !== '' ? value.trim() : null;
 const toProductCode = (value) => value
     .trim()
     .toLowerCase()
@@ -91,13 +90,24 @@ const buildSubFamilyPayload = (localData, subFamily, clearEmptyValues, lookup) =
 /** `unit` is the item's unit of measure, not a currency; `CURRENCY_CODE` above prices Price points. */
 const DEFAULT_CATALOG_ITEM_UNIT = 'USD';
 /**
- * Build the parent catalog-item request body from the form draft. Creates omit
- * both parent and price point IDs; edits retain returned price point IDs.
+ * Build the parent catalog-item request body from the form draft. Every field
+ * the form holds is sent, so a value cleared on the form is cleared on the
+ * item: the service reads an absent key as "leave it alone", which is why
+ * `description` travels as an empty string and `applicable_items` as an empty
+ * list rather than being dropped. Fields the form does not collect
+ * (`external_name`, `item_family_id`, `metadata`, …) stay off the body so an
+ * edit cannot overwrite them with a value nobody chose.
  */
 export const localDataToSaveInvoicingCatalogItemPayload = (localData, isCreate, lookup) => {
-    const description = trimOrUndefined(localData.description);
     const productCode = trimOrUndefined(localData.productCode) ?? toProductCode(localData.name);
     const itemPayload = {
+        // `applicable_items` only means anything while the item is restricted;
+        // sending the empty list otherwise is what clears a restriction that was
+        // just lifted.
+        applicable_items: localData.itemApplicability === 'restricted'
+            ? localData.applicableItems
+            : [],
+        description: trimOrUndefined(localData.description) ?? '',
         enabled_for_checkout: true,
         enabled_in_portal: true,
         is_giftable: false,
@@ -107,41 +117,40 @@ export const localDataToSaveInvoicingCatalogItemPayload = (localData, isCreate,
         name: localData.name.trim(),
         product_code: productCode,
         type: localData.catalogType,
+        // The form no longer collects a unit; an item that already has one keeps it.
+        unit: trimOrUndefined(localData.unit) ?? DEFAULT_CATALOG_ITEM_UNIT,
     };
-    if (description != null) {
-        itemPayload.description = description;
-    }
-    // The form no longer collects a unit; an item that already has one keeps it.
-    itemPayload.unit =
-        trimOrUndefined(localData.unit) ?? DEFAULT_CATALOG_ITEM_UNIT;
-    if (localData.itemApplicability === 'restricted' &&
-        localData.applicableItems.length > 0) {
-        itemPayload.applicable_items = localData.applicableItems;
+    // The external id is assigned by the billing service and shown read-only, so
+    // it is echoed back only when the item already has one: sending the blank a
+    // create starts with would clear an id assigned in the meantime.
+    const externalId = trimOrUndefined(localData.externalId);
+    if (externalId != null) {
+        itemPayload.external_id = externalId;
     }
     const subFamilies = localData.subFamilies.length > 0
         ? localData.subFamilies
         : [blankInvoicingCatalogSubFamily()];
-    itemPayload.sub_family_details = isCreate
+    itemPayload.sub_families = isCreate
         ? subFamilies.map((subFamily) => buildSubFamilyPayload(localData, subFamily, false, lookup))
         : subFamilies.map((subFamily) => {
-            const priceCode = trimOrUndefined(subFamily.priceCode) ?? toProductCode(subFamily.name);
-            const detail = {
-                description: trimOrNull(subFamily.description),
-                invoice_notes: trimOrNull(subFamily.invoiceNotes),
-                name: subFamily.name.trim(),
-                price_code: priceCode,
-                show_description_in_invoices: subFamily.showDescriptionInInvoices,
-            };
-            // Edits send a narrower body than creates, but the accounting mapping
-            // is editable on this form, so leaving it out dropped the account and
-            // class the user had just picked. `null` rather than omitted when it is
-            // empty: an absent key on an update reads as "leave it alone", which
-            // would make a cleared mapping impossible to save — the same reason
-            // `description` and `invoice_notes` go through `trimOrNull`.
+            // Edits send the same body a create does. The narrower hand-built one
+            // this replaces had to be kept in step by hand and was not: it dropped
+            // `accounting_detail` once, and `billing_cycles`, `price`,
+            // `pricing_model`, `period`, the trial fields, `proration_type`,
+            // `free_quantity`, `is_taxable` and `tiers` were never added at all, so
+            // editing any of them looked saved and changed nothing.
+            const detail = buildSubFamilyPayload(localData, subFamily, true, lookup);
+            // `null` rather than omitted when empty: an absent key on an update
+            // reads as "leave it alone", which would make a cleared mapping
+            // impossible to save — the same reason `description` and
+            // `invoice_notes` are cleared rather than dropped above.
             detail.accounting_detail =
                 buildAccountingDetail(subFamily, lookup) ?? null;
-            const id = trimOrUndefined(subFamily.id);
-            return id != null ? { ...detail, id } : detail;
+            // A price point added on this form has no id yet, and travels with a
+            // blank one. The update endpoint reads that as "create this one", so it
+            // lands in the same request as the edits around it rather than a second
+            // call that could fail on its own.
+            return { ...detail, id: subFamily.id.trim() };
         });
     return itemPayload;
 };