Lifecycle actions and transactions

What it is

Two families of operator action:

Lifecycle — changes to the supplier’s standing: hidden, suspended, locked, cancelled, written off, deleted, or won back.

Transactions — money and data operations available from the global Actions menu regardless of which tab you are on: earnings and remittance loads, chargebacks, recoveries, receivables, write-offs, statement and payment adjustments, and fund transfer requests.

Both are implemented as dialogs under suppliers/supplier/, each with its own service, following a shared pattern established by suppliers/supplier/base-supplier-action/.

Status vocabulary

shared/consts/supplier-status.enum.ts:

export enum SUPPLIER_STATUS {
  ACTIVE             = 'Active',
  PENDING_ACTIVATION = 'Pending Activation',
  PENDING            = 'Pending',
  SUSPENDED          = 'Suspended',
}

SupplierStatusModel is a much richer rollup than the supplier record itself, and is what the header badges read:

Field Meaning

supplierStatus

SUPPLIER_STATUS.

hasMarketplaces, legalSigned, instantAccess, generalInfoUpdated

Readiness gates.

fundPartStatus

Funding-particulars status (Not Selected / Selected / Sent / Rejected / Declined / Approved).

ascApiStatus

Amazon Seller Central API health.

pmtCfgStatus, pmtCfgProvided, hasPaymentHistory

Payment-configuration readiness.

nextPayment, enrollmentStart

Schedule dates.

hasReceivablePurchase

Whether receivables have been purchased.

efsAccount

Whether an EFS card account exists.

hasAutoTransferEnabled, autoTransferMinimumBalanceToStay, hasForwardPaymentEnabled

Automatic transfer configuration.

supAdvStatus, supAdvLiability

Advance status (Active / Offer Pending / Closed / None) and outstanding liability.

SupplierStatusesService maps each status vocabulary to a Bootstrap badge class, with 'badge badge-light' as the fallback for unknown values. Six dictionaries: supFundPartStatusDictionary, mpFundPartStatusDictionary, payConfigStatusDictionary, supplierStatusDictionary, supplierCancelationStatusDictionary (none / pending / canceled) and advanceStatusDictionary.

These dictionaries are keyed on the backend’s display strings, not codes. A wording change upstream silently degrades every badge to the neutral fallback rather than throwing.

Lifecycle actions

Action Implementation Notes

Hide / unhide

toggle-hide-supplier/; TOGGLE_HIDE_SUPPLIER in the supplier slice

Hides the supplier from lists. The reducer flips supplierDetailsModel.hide locally on success rather than re-reading it.

Suspend

suspend-supplier/; TOGGLE_SUSPEND_SUPPLIER

Sets status to Suspended. The reducer records only progress/error — the model is refreshed by re-fetch.

Lock / unlock

supplier-unlock/; TOGGLE_LOCK_SUPPLIER; supplierLocked on the details model

Actions and effects exist but the reducer has no cases for them, so lock state only updates on re-fetch.

Cancel

cancel-supplier/; CancelSupplierService (+ mock)

See below.

Win back

winback-confirmation-modal/; WinbackService

Re-activates a cancelled supplier. Reasons from winback/reasons.

Write off

add-writeoff/; writeoff on the details model

Requires MANAGE_BAD_DEBT.

Request collection

request-collection/; RequestCollectionService

Full CRUD on suppliers/:key/collections plus suppliers/:key/collections_reasons.

Delete account

delete-supplier-account/; DeleteSupplierAccountService; flag DELETE_SUPPLIER

See below.

Change password / reset

supplier-change-password-dialog/; shared/reset-password/ at /reset-password

Operator-initiated credential reset.

Cancellation

CancelSupplierService on internalApiUrl:

Endpoint Purpose

GET active_marketplaces/:supplierKey

Which marketplaces are still active — a cancellation precondition check.

GET suppliers/:supplierKey?taxId=1

Supplier detail including tax id, for the confirmation screen.

GET cancellation_reasons

The reason list.

PUT suppliers/:supplierKey/acc_cancellation

Perform the cancellation.

GET suppliers/:supplierKey/get_acc_cancellation_reason

Read the recorded reason.

POST suppliers/:supplierKey/change_acc_cancellation_reason

Amend the reason after the fact.

cancelationStatus on the details model tracks none / pending / canceled — so cancellation is a two-stage process, not immediate.

CancelEmitService (its own CancelEmitModule.forRoot(), imported in AppModule) is a small Subject bus that notifies the workspace when cancellation or win-back state changes, so panels re-render without a store round trip:

onCancellationChange:     Subject<boolean>
onWinbackChange:          Subject<void>
editOnCancellationChange: Subject<string>

setCancellation() toggles an internal boolean and emits it. It does not take the new state as an argument, so two callers can desynchronise it from reality. Treat it as a change notification, not a source of truth.

Account deletion

DeleteSupplierAccountService, behind the DELETE_SUPPLIER feature flag:

GET  supplier/:supplierKey/remove_supplier_account   → { can_be_removed, … }
POST supplier/:supplierKey/remove_supplier_account   → perform deletion

canBeRemoved() maps can_be_removed and catches errors to false — a failed precondition check reads as "cannot be removed", which is the safe default.

Note the path segment is singular supplier/, unlike almost every other endpoint (suppliers/). Easy to mistype.

The Actions menu

The sidebar Actions group is visible only when the layout slice says actionsVisible (true on supplier pages, not on the list) and the user is not REST_UW_ACCESS / ADVANCE_AUDITORS. Items:

Menu item Folder What it does

Import ▸ Load Earnings

load-earnings/

Starts a marketplace earnings load. Long-running — progress arrives over the B2B task-manager SSE stream. Can also be triggered by EVA via ONBOARDING__INIT_LOAD_EARNINGS_PROCESS.

Import ▸ Load Remittance

load-remittance/

Loads the marketplace remittance. Conditionally shown (shouldShowRemitance in the sidebar component).

Add chargeback

add-chargeback/

Charges a reversal back to the supplier’s balance.

Add Bad Debt Recovery

add-recovery/

Records a recovery against a written-off balance (MANAGE_BAD_DEBT).

Add receivable

add-receivable/ with service/receivable.service.ts (provided in AppModule)

Adds a receivable to fund against.

Add writeoff

add-writeoff/

Recognises an unrecoverable balance.

Add New Default Contract

add-contract/

Only shown when isSupplierActive. See contracts.

Edit MP Statement

edit-marketplace-statement/

Corrects a marketplace statement (MP_STATEMENTS_MODIFY / MP_STATEMENTS_DELETE).

Add MP Payment

add-marketplace-payment/

Records a marketplace payment (INT_MP_PMTS).

Add Zero MP Payment

add-zero-marketplace-payment/

Records a zero-value marketplace payment — used to close a period with no payout.

Adjust Payability Fee

adjust-payability-fee/

One-off fee adjustment (INT_FEE_UPD), distinct from fee schedules — see fees and reserves.

Add Fund Transfer Request

create-transfer-request/ with suppliers/model/transfer-payment-details.model.ts

Requests a fund transfer, which becomes part of a batch — see processes.

Also present but reached from elsewhere: add-marketplace-statement/, marketplace-access-details/, actions-import-menu/, transaction-modal/, kyc-documentation/, supplier-statements/.

shared/actions-menu/ and shared/actions-add-fabs/ provide the menu and floating-action-button shells; crm-tools/actions-add-fabs/ is the CRM equivalent.

Operation Implementation

Log in as supplier

suppliers/services/login-as-supplier/login-as-supplier.service.ts using env.supplierUrl, with SupplierAuthTokenService (authToolsApiUrl) issuing the token and SupplierService.getToken() (suppliers/:key/get_token). Requires the companion browser extension — hence messageCodes.installExtension and cantReceiveToken in MessageService. In test environments only supplier and supplier4 sites are permitted (inTestEnvironmentsCanOnlyTo). The EVA message MAIN_HEADER__LOGIN_AS_SUPPLIER triggers the same flow from the embedded header.

Log in to Amazon

PybExtensionService plus the MAIN_HEADER__LOGIN_TO_AMAZON message.

Referral link

suppliers/services/supplier-referral.service.ts using env.supplierReferralUrl.

Email preferences

suppliers/services/supplier-email-preferences.service.ts and supplier-email-preferences/ — see emails.

Deal link

extDealId on the supplier plus MAIN_HEADER__NAVIGATE_BY_DEAL_LINK — jumps to the external sales CRM.

Permissions relevant to lifecycle actions

Permission Gates

INT_XACT_CNCL

Transaction cancellation.

INT_FEE_UPD

Fee adjustments.

INT_MP_PMTS

Marketplace payments.

INT_RCV

Receivables.

MANAGE_PMT

Payment management.

MANAGE_BAD_DEBT

Write-offs and bad-debt recovery.

MP_STATEMENTS_MODIFY, MP_STATEMENTS_DELETE

Marketplace statement edits.

MP_LOANS_MODIFY, MP_LOANS_DELETE

Amazon-lending loans (enforced by SubPermissionsGuard on the route).

INT_SUP_CRED

Supplier credentials.

INT_UPDATE, INT_SUPER_USER

General update and super-user.

The client hides UI for these; the backend enforces them. See authorisation and the permission catalogue.

Gotchas

Issue Detail

Optimistic hide, pessimistic suspend

The hide toggle flips local state on success; suspend and lock do not. Three toggles, three different refresh behaviours.

TOGGLE_LOCK_SUPPLIER has no reducer case

The action round-trips but the store is not updated. Re-fetch to see the result.

Singular supplier/ in delete endpoints

Unlike every neighbouring endpoint.

CancelEmitService.setCancellation() toggles blindly

It does not accept the intended state.

Status badges key on display strings

Backend wording changes degrade badges silently.

Zero MP payment is a real operation

It is not a no-op guard against mistakes; it records a zero-value payment deliberately.

Load Earnings/Remittance are asynchronous

They return before the work completes. Progress comes from the SSE stream — see real-time streams.