S50 — Required sale details (pp_rsd): the details a customer group gives before paying

The retailer decides which sale details a group of its customers must give before they pay: an account customer's purchase order number, an insured patient's policy number, a contractor's project. When the cashier presses Pay and a detail the customer's group needs is empty, the till refuses the sale in the retailer's words. The cashier fills the detail under the sale's details and presses Pay again.

When to use it: a sale detail matters for some customers only. A Sale Attribute's own Required switch holds for every customer on every till; this app holds it for the groups and tills the retailer names.

What happens

What the retailer and the cashier see (on a demo site, 2026-10-24)
What the install will change, read before you consent
A rule for a customer group: one sale detail needed, at one POS Profile, with the words the cashier reads
The check switched on for one POS Profile, with what it is sent
At Pay, the detail empty: the sale refused in the rule's words
The cashier fills the detail under the sale's details, then presses Pay again

Which rule decides. One rule per customer group: the sale details needed, and the POS Profiles it holds on (none: every till). A customer takes their own group's rule; a group with no rule takes the rule of the nearest group above it in the retailer's customer group tree. A group's own rule replaces the rule above it entirely, so a rule with no details lets a group off:

A contractor buying at the trade counter gives both; at any other till, nothing (their own rule replaces the account customers' rule). The store's walk-in customer is in a group too: a rule on its group asks every walk-in sale (for a mobile number, say); a rule on All Customer Groups asks the walk-in customer and every customer below it with no rule of its own.

What the retailer does

Before you install: every host.docker.internal address in manifest.json (in allowed_urls, and where the manifest calls it) is our test bench's own address for the sample's service, and it resolves only where Docker provides it. Replace it with your own service's address first, or iVendNext's calls never reach your service; if this manifest is already installed, raise its version and install it again (the manifest recipe, step 6).

1. Install the app from the App library (or paste its manifest into Retail Extension Package in Desk), read what it will do and consent. The install adds the record type PP RSD Rule with its two tables, the role PP RSD Integration, the check and the feed registration, the check switched off. Nothing changes at the till yet.
2. Make the app's integration user (the integration user recipe): tick Is Desk User, give it the role PP RSD Integration alone and generate its API key. In Role Permissions, give that role read on Customer Group (the service reads the group tree). Choose the user on the feed registration PP RSD Rules feed.
3. Stop cashiers moving a customer into another group. The till's edit sheet lets a cashier change a customer's group: a cashier could move a customer into a group that needs nothing. In Customize Form for Customer, set Customer Group's Perm Level to 1, and in Role Permissions give level 1 Write on Customer only to the roles that may move customers (your managers). A cashier's change then leaves the group as it was, and the till still says Customer saved.; a cashier can no longer give a new customer a group either (it takes the default customer group). Check the level 1 rows already there: Sales Master Manager has one by default, and no cashier's role may hold level 1 Write. (Measured with S47; S46 gives the same step.)
4. Make the sale details the rules name, in Sale Attribute (iVendNext's own screen): one per detail, such as Purchase order number, with a Sequence of its own (no other active detail may hold it), switched on (Active), and no Default Value (a default fills the detail for the cashier, so the check passes with nothing typed). Leave its own Required off: this app decides who must give it. Its Regex Pattern still checks the value's shape for everyone who fills it. A detail switched off, or hidden by a field rule, cannot be filled at the till: take it off the rules first, or every sale for that group is refused.
5. Write the rules in PP RSD Rule: one per customer group that needs one. Words the cashier reads is optional.
6. Switch the check on: open Required sale details in Retail Extension Subscription, read what is sent, tick the consent, choose the POS Profiles, and switch it on. Last, press Connect again on the app's record, which sends the integration user's key to the service.

Where it shows. The rules are Desk records the retailer keeps (its System Manager, or a role the retailer gives the rights to in Role Permissions: that role also needs Select on Customer Group, Sale Attribute and POS Profile, or the rule's lookups answer nothing; a System Manager too, where the site removed it). At the till the cashier meets them at Pay.

What leaves the retailer's iVendNext. At Pay, and before each refund the till pays, the priced basket goes to the service's address: each line's item, group, quantity and amounts, the totals, the store, till, POS day and terminal, the cashier's user, the customer and their customer group, the coupons, the payment methods offered, and the sale's details with the values the cashier typed (a purchase order number, a policy number, a phone number); never a card. The service reads the retailer's rule records and its customer group tree with the integration user's key, keeps them one minute, and keeps nothing of a sale. It writes nothing. A hosted copy holds each retailer's check secret and its user's API key from Connect again until the retailer removes the app. Say so on your card.

The files

Run it

python3 -m unittest discover -s samples/s50_required_sale_details/tests -p 'test_*.py'

python3 samples/s50_required_sale_details/tests/canaries.py

python3 samples/s50_required_sale_details/service/app.py samples/s50_required_sale_details/service/.env.local

Settings, one retailer (service/.env.local, never committed): IVN_CHECK_SECRET (handed back at install as pp_rsd:sub:details), IVN_SHOP_URL, IVN_SHOP_KEY (<api key>:<api secret> of the integration user), PORT. RSD_PREFIX names the rule record type (default PP RSD).

Many retailers, hosted

The service is the app template's shape: set IVN_LIBRARY_APP and a store (IVN_SHOPS_TABLE on CitiXsys hosting, else IVN_SHOPS_FILE). Each retailer connects itself after its install and hands over the check's secret; Connect again hands over its integration user's key. Until the key arrives the service answers 503 and the down answer applies. Every call names its retailer (X-iVendNext-Site), and each retailer is answered from its own rules with its own key.

Make it your own

What a partner usually changes:

• the value, not only its presence: a policy number checked with the insurer, a purchase order number checked against the customer's open orders (read them with the integration user);
• line details: a detail per line for some item groups (the check sends each line's line_attributes);
• the rule's reach: a rule per customer, from a field you add to Customer, or per terminal (the check sends pos_terminal);
• the prefix: tools/manifest/rename.py makes your copy under your own reserved prefix in one step; the service takes its prefix from RSD_PREFIX;
• its records: tools/deploy/copy_records.py moves the rules between a test site and the retailer's iVendNext.

Before you copy it

• Present, not right. The app checks that a needed detail holds something other than spaces. Its shape is the Sale Attribute's own Regex Pattern, which holds for every sale that fills it.
• Down means the sale goes on. The manifest declares allow_and_flag: an outage never stops a retailer selling, and a sale the rules could not judge is flagged on Sales to review. A retailer that must never take such a sale sets the check's down answer to refuse; every sale on that POS Profile then waits on the service. A refused key (401 or 403) is iVendNext unreadable too, never an allow without the flag.
• The customer's group is the retailer's. The rule reads the group the customer record holds: put Customer Group at a permission level only your managers write (step 3).
• A rule changed in Desk, or a new customer group, reaches the service within a minute (it keeps the rules and the tree that long).
• A long list of details is cut in the app's own sentence (the till shows at most 140 characters): write the rule's own words when a group needs more than two or three.
• Three checks a POS Profile. At most three checks answer one POS Profile, ten seconds together; this one asks for 3, so two other check apps fit beside it.
• Your address. Write your own address in allowed_urls. The retailer's server must trust your certificate: a real one for a retailer.

Technical notes

Why it is built this way

The answer, exactly

• The reads: GET /api/resource/<prefix> Rule with fields ["name","customer_group","words","details.sale_attribute","profiles.pos_profile"] (one row per detail and POS Profile), filters [["enabled","=",1]], limit_page_length 0; and GET /api/resource/Customer Group with ["name","lft","rgt"]. Both at once (each read has its own timeout inside the check's 3 s), kept a minute per retailer and per key. Either one failing answers 503: never a decision on half the retailer's rules.
• The rule that decides is the customer's own group's, else the innermost group whose span (lft, rgt) holds the group's and that has a switched-on rule. A customer with no group takes the outermost group's rule. A group the tree does not know needs nothing unless it has its own rule.
• Where it holds: at every till when the rule names no POS Profile, else only at the pos_profile it names.
• The details missing are the rule's details, in its order, that the sale's sale_attributes do not hold with a value other than spaces and direction marks. None: allow. Any: refuse with the rule's own words (up to 140 characters), else "Customers in ⟨group⟩ need ⟨details⟩. Fill in the sale's details, then Pay." (a group cut at 30 characters, the list at 52, so the instruction is never cut).

Bounds, stated

• A sale only. A refund, a return against a sale, the returned items of an exchange and a return without its sale (stage: "return") are allowed without reading iVendNext. An exchange's replacement basket is stage: "sale" and is judged, except an exchange rung without its sale when nothing is owed: the till sends it as a return with its sold lines, and this app allows it (the contract lets a check judge those lines by its sale rule; a partner's version may, with a sentence that does not say then Pay).
• The sale's details, not a line's. Line details are a partner's version.
• An exchange or a sale from a quote is refused with no place at the till to fill the detail (read in the till's code, not walked): fill it on the quote first; refund and ring a new sale instead of an exchange. A sale-details entry on those two screens is asked of the POS app.
• A rule per customer group. A customer's own rule is a group of their own.
• Offline, the till does not call the service: the sale is flagged when it syncs, never refused.
• Where the check never runs: a park to a till, a layaway deposit, an account collection (the check page, Not in this version) and the Desk's own POS screen.
• Where it runs: the App library's copy runs in CitiXsys hosting's US region. On CitiXsys hosting the first Pay after a quiet spell starts the function; past 3 s the down answer applies, flagged.
• It logs one line per call: the route, the status and the milliseconds, never the body.

This page in the kit