Skip to main content

B2B Customer

Customer​

This document describes the B2B Customer feature in the Checkout App. B2B Customer lets a cashier attach a business customer — optionally together with an agent and a project — to a transaction, so the sale can be tracked and invoiced against that customer's account. It is available on POS and MPOS.

Overview​

B2B Customer enables:

  • Searching for and selecting a business customer by name, external customer ID, phone, or address
  • Optionally requiring an agent and/or a project on the transaction, depending on the customer record
  • Collecting customer-specific additional inputs (dynamic fields defined per customer) before the customer is added
  • Displaying the customer, and their available credit, on the receipt
  • Alerting the cashier when the amount due exceeds the customer's available credit limit
  • Editing or removing the B2B customer (and its agent/project) from an in-progress transaction

Configuration​

B2B Customer is enabled via CCC configuration using the cha.settings.v1 schema. POS and MPOS are enabled independently. Both flags default to false when omitted, and there are no sub-flags — search, additional inputs, and the credit limit alert are all part of the same feature and are always active once the relevant flag is enabled.

See CCC Configurations for the configuration reference.

Starting a B2B Customer Selection​

  1. Click the B2B shortcut (available in the shortcuts area on desktop/tablet, or under More on phone)
  2. The B2B search view opens

On desktop and tablet, the view shows three tabs — Customer, Agent, Project — plus a selection summary panel. On phone, the view is a single selection screen with a separate Add action per section (Customer, Agent, Project) that opens its own search screen.

Note: The Agent and Project tabs/actions are disabled until a customer has been selected.

Searching for a Customer​

  1. In the Customer tab (or the Customer Add action on phone), enter one or more filters: name, external customer ID, phone, or address
  2. Click Search
  3. Select a row from the results (Name, Phone, Address, Status)

Note: Customers with status Inactive cannot be added — the Add action is disabled for inactive rows.

Additional Inputs​

If the selected customer has additional inputs configured, an Additional Inputs screen appears before the customer is added:

  1. Fill in the required fields (each field's label, required state, and validation pattern come from the customer record)
  2. Click Save

The customer is only added to the draft selection after additional inputs are completed. If the customer has no additional inputs configured, it is added directly.

Searching for an Agent or Project​

Once a customer is selected, the Agent and Project tabs/actions become available. Agent and project search automatically scope to the selected customer:

  • Agent search results show Name and whether identification is required
  • Project search filters include name, address, city, and a from/to date range; results show Name, Address, City, From Date, To Date, and Status (Active, Upcoming, or Expired)

If the customer record requires an agent and/or a project (requireAgent / requireProject), the corresponding section in the selection summary is marked Required until filled in.

Submitting the Selection​

The submit (checkmark) button is enabled only when:

  • A customer has been selected, and
  • An agent is selected if the customer requires one, and
  • A project is selected if the customer requires one

Submitting sends the full selection (customer, agent, project, additional input values) to the transaction. On success, the B2B customer appears on the receipt.

On the Receipt​

Once a B2B customer is on the transaction, a banner appears above the totals showing the customer name, with Edit and Remove actions. Edit and Remove are only available while the transaction is still active (not suspended or finalized).

If the customer has a credit limit, the receipt totals also show an Available credit line:

  • The remaining available amount, or
  • Blocked, shown in red, if the customer's status is credit-blocked

On phone, the available credit / blocked state is also shown as a second line under the customer name in the receipt banner.

Editing or Removing the B2B Customer​

  • Edit reopens the B2B search view, pre-populated with the current customer, agent, and project
  • Remove prompts for confirmation, then removes the customer, agent, and project from the transaction together — they cannot be removed individually

Credit Limit Alert​

If the customer has a credit limit and is not already credit-blocked, the app checks whether the amount due exceeds the customer's available credit. This check runs whenever the cashier returns to the main transaction screen (for example, after adding items or navigating back from another screen).

When the amount due exceeds the available credit, an alert dialog is shown:

Available credit limit reached Amount due is past the available credit limit of {limit}.

Dismissing the alert (OK) acknowledges it for the current state;

Note: This alert is informational only. It does not block the transaction or restrict tender selection in the Checkout App — credit-blocked enforcement (e.g. disallowing invoice tender) is handled server-side by the Checkout Engine.

Recovery After Restart​

If the Checkout App restarts (for example, after a crash) while a B2B customer is on the transaction, the customer, agent, and project are re-fetched from the backend using the IDs stored on the receipt, and the receipt banner shows a loading indicator while this happens.

Invoice Settlement​

Overview​

The B2B Invoice Settlement feature allows cashiers to settle previously issued invoices directly from the Checkout App.

Depending on the tenant configuration, cashiers can:

  • Select invoices using an embedded invoice management page.
  • Enter an invoice number and amount manually when required by adding the assigned item from e.g. PLU.

Prerequisites​

Before enabling B2B Invoice Settlement, ensure that:

Configuration​

The embedded invoice management page requires In-App Links to be enabled. Settling invoices is enabled via CCC configuration using the cha.settings.v1 schema via b2bCustomer.invoiceSettlement;

The same configuration is available under mpos.

Note: shareAuthorizationToken must be enabled if the micro frontend authenticates using the Checkout App session.

B2B Invoice Settlement Integration contract​

Once a cashier has selected an invoice in the micro frontend, the micro frontend must return the invoice details to the Checkout App using a supported in-app link.

Returning Invoice Data to the Checkout App​

After the cashier has selected an invoice and confirmed the selection, the micro frontend must navigate to the following link:

hii://checkout/invoice/add?invoice_number=invoice&amount_due=amount&customer_id=customer_id

The Checkout App intercepts this in-app link and extracts the invoice information from the URL parameters. Navigation to this link does not load a new page in the embedded browser. Instead, it triggers the invoice settlement flow in the Checkout App.

Checkout App Behaviour​

Upon receiving the in-app link:

  1. The Checkout App extracts the invoice information from the URL parameters.
  2. A confirmation dialog is displayed:
    • Title: Confirm invoice settlement
    • Message: Add Invoice invoice_number with amount amount_due currency?
  3. If the cashier selects No, the confirmation dialog is dismissed and the embedded invoice page remains open.
  4. If the cashier selects Yes, the Checkout App adds the configured virtual invoice settlement item to the transaction and cashier may continue the payment flow.