Home ›Specs

SDD — NCR Counterpoint Retail Spine Integration

1. Architecture overview

┌────────────────────────────────┐         ┌──────────────────────────┐
│  Customer site (e.g. H&G chain)│         │  Canary infrastructure   │
│                                │         │                          │
│  ┌──────────────────────────┐  │         │  ┌────────────────────┐  │
│  │  NCR Counterpoint v8.5+  │  │         │  │  TSP Counterpoint  │  │
│  │  (Windows on-prem)       │  │         │  │     adapter        │  │
│  └────────────┬─────────────┘  │         │  └─────────┬──────────┘  │
│               │ TLD            │         │            │             │
│               ▼                │         │            ▼             │
│  ┌──────────────────────────┐  │ HTTPS   │  ┌────────────────────┐  │
│  │  Counterpoint REST API   │◄─┼─────────┼──┤  Polling / fetch   │  │
│  │  Server (.NET 4.5.2)     │  │ Basic+  │  └─────────┬──────────┘  │
│  │  Windows host, 8889 etc. │  │ APIKey  │            │             │
│  └──────────────────────────┘  │         │            ▼             │
│                                │         │  ┌────────────────────┐  │
└────────────────────────────────┘         │  │  CRDM (Postgres)   │  │
                                           │  └─────────┬──────────┘  │
                                           │            │             │
                                           │            ▼             │
                                           │  ┌────────────────────┐  │
                                           │  │  Downstream Canary │  │
                                           │  │  modules (Chirp,   │  │
                                           │  │  Fox, dashboards)  │  │
                                           │  └────────────────────┘  │
                                           └──────────────────────────┘

Path: Counterpoint REST API → TSP Counterpoint adapter → CRDM → downstream Canary modules.

Network: Counterpoint API server is at the customer's site, on Windows. Canary's adapter polls / fetches from it over HTTPS using HTTP Basic auth + APIKey header. Customer-provided host or Canary-provided edge box is a per-deployment decision (see §10 Risks).

2. Source-of-truth references

3. Authentication + authorization

Endpoint class Auth APIKey required? Notes
System administration (/AdminUsers, /APIKey, /Database, /Roles, ...) HTTP Basic with system admin creds Per endpoint — see Endpoints/ Used during initial setup; rare in steady state
Company functions (everything operational: customers, items, transactions, ...) HTTP Basic with <company>.<username>:<password> Yes (most) Per Counterpoint company; multi-company deployments use multiple credentials

Per-customer auth bootstrap: 1. Customer's Counterpoint license must have the API user option enabled in registration.ini (paid add-on; bulk of endpoints require it). 2. NCR-issued APIKey installed on the customer's Counterpoint API server. 3. Canary-side: store credentials per tenant (encrypted at rest); rotate quarterly.

Cross-cutting auth concern: Canary's TSP must NEVER store unencrypted Counterpoint credentials. Use Canary's standard secret-store; rotate via the secret-rotation runbook (see docs/audit-2026-04-23/secret-rotation-runbook.md).

4. CRDM alignment

Canary's CRDM uses 5 entity classes (People × Places × Things × Events × Workflows). Counterpoint endpoints map across them. The table below is the class-level summary; per-endpoint detail lives in Brain/wiki/ncr-counterpoint-endpoint-spine-map.md.

CRDM class Counterpoint endpoint groups Spine modules
People Customer*, Customer_Address, Customer_Note, Customer_OpenItems R, C
Places Store*, Store_Station, Device_Config; InventoryLocations N (Store/Device); D (InventoryLocations primary)
Things Item, ItemCategor, ItemSerial, Item_Images, Item_Inventory, Inventory, GiftCard (code/template definitions only) S, A
Events Document (sales tickets/transactions); GiftCard (transactions + tender activity); returns/voids embedded in Document T, F (GiftCard primary as tender), Q
Workflows EC (ecommerce), forecasting/ordering endpoints (per Endpoints/ — verify), tasks where supported W, J, C
Platform / cross-cutting AdminUser*, Roles, RoleUsers, RoleEndpoints, APIKey, Database, SystemInfo, CACHE platform (no spine letter — API server self-administration; out of CRDM)

Mapping refinements vs draft-1 (recorded 2026-04-25 after per-endpoint extraction): - AdminUser/Roles → Platform. Earlier draft put them under People (R/L/C). They are API-server self-administration, not customer or labor data. Moved off People, onto a new Platform row. - GiftCard* → Events / F primary. Earlier draft put them under Things (S/A/P). Per-endpoint reading: gift card codes/templates are catalog entries (S, secondary), but the endpoint surface is dominantly transaction/tender (F, primary). The "P" attribution was not defensible. - InventoryLocations → D primary. Earlier draft listed N, D for the whole Places row. InventoryLocations is dominantly a Distribution concept (transfers, multi-location stock); Stores and Devices remain N. Both modules retained on the row, with D explicitly primary for InventoryLocations.

Per-module mapping detail in §6 below.

5. ARTS standards alignment

Counterpoint emits ARTS-compatible structures (verified via onlinehelp.ncr.com Advanced Store + ACS docs):

Out of scope: non-ARTS extensions specific to Counterpoint that don't have an ARTS analog (per-module §6 calls these out).

6. Module-by-module mappings

For each module: spine intent, Counterpoint endpoints, CRDM entities, ARTS alignment, MCP tool surface, TSP adapter notes, open questions.

6.1 Module T — Transactions

6.2 Module C — Customer

6.3 Module N — Device

6.4 Module A — Asset Management

6.5 Module Q — Loss Prevention

6.6 Module M — Commercial

6.7 Module D — Distribution

6.8 Module F — Finance

6.9 Module O — Forecast / Order

6.10 Module S — Space / Range / Display

6.11 Module P — Pricing / Promotion

REVISED 2026-04-25 post deep-dive: Counterpoint's REST API has no dedicated Pricing or Promotion endpoint family. Module P is derived, not directly mapped. See Brain/wiki/ncr-counterpoint-api-reference.md.

6.12 Module L — Labor / Workforce

REVISED 2026-04-25 post deep-dive: Counterpoint's REST API has near-zero workforce coverage. No Employee, Timeclock, Schedule, or Labor-cost endpoints exist. SDD's prior open question §6.12 (timeclock via REST) is answered: NO. Module L cannot be sourced from Counterpoint.

6.13 Module E — Execution

REVISED 2026-04-25 post deep-dive: Counterpoint's REST API has no work-execution / task / checklist endpoints. Module E is fully out of Counterpoint scope.

7. Cross-cutting concerns

7.1 Idempotency

All TSP upserts keyed on Counterpoint primary keys (e.g., customer_id, document_id, item_id). Replay-safe. Adapter writes are idempotent UPSERTs at the CRDM boundary.

7.2 Error handling

HTTP status Handling
200 OK Process response
401 Unauthorized Re-authenticate; rotate creds if 401 persists after re-auth
403 Forbidden Check APIKey + per-endpoint role permissions; surface to operator
404 Not Found Log as warning; continue
429 Too Many Requests Exponential backoff; alert if sustained
5xx Backoff + retry (3x, exponential); alert if 3 retries fail

7.3 Batching + pagination

7.4 Monitoring + alerting

7.5 Multi-version Counterpoint

7.6 Multi-company

8. Implementation phasing

Reproduced from build plan; canonical source is docs/superpowers/plans/2026-04-25-ncr-counterpoint-spine-build.md.

Phase Modules Output
0 TSP rebuild + CRDM + adapter shell foundation, no module endpoints yet
1 T, R, F, L, N priority modules
2 P, S catalog modules (H&G-critical)
3 D, W, J operations modules
4 A, C, Q tertiary modules (Q comes last because it consumes earlier modules)
5 cutover + monitoring runbook + alerting + capacity

9. Acceptance criteria

Per-module:

Program-level (see build plan §Acceptance criteria for full list):

10. Risks

(Reproduced + extended from build plan)

11. Open questions (status updated 2026-04-25 post deep-dive)

# Question Status
1 Does Counterpoint expose ticket-line items as nested in Document or as separate endpoint? ANSWERED — NESTED. Lines are in PS_DOC_LIN[] array on the Document response (per Brain/wiki/ncr-counterpoint-document-model.md). POST_Document_Lines exists for adding lines but reads come whole.
2 How does Counterpoint distinguish void-of-sale from return at the data-model level? Mostly answered — Documents reference originating tickets via PS_DOC_HDR_ORIG_DOC[] array; return vs. void distinguished by DOC_TYP code (exact codes pending verification with non-sale samples)
3 Customer-tier representation in CustomerControl — how many tiers, how named? ANSWERED. Customer tier = CATEG_COD field on the Customer record (e.g., "MEMBERS"). User-defined codes; not enumerated at CustomerControl level. CustomerControl carries system-level customer config (aging periods, custom-field enablement, loyalty enabled flag) but not tier definitions.
4 Loyalty program data — separate endpoint or embedded in Customer? ANSWERED — EMBEDDED. Customer record has LOY_PGM_COD, LOY_PTS_BAL, TOT_LOY_PTS_EARND, TOT_LOY_PTS_RDM, TOT_LOY_PTS_ADJ, LOY_CARD_NO, LST_LOY_EARN_TKT_DAT/TIM, LST_LOY_PTS_EARN, LST_LOY_EARN_TKT_NO, LST_LOY_PTS_RDM, LST_LOY_ADJ_DAT, LST_LOY_PTS_ADJ. CustomerControl has USE_LOY_PGMS: Y/N system flag.
5 Does Counterpoint expose timeclock via REST? ANSWERED — NO. Module L cannot be sourced from Counterpoint REST. See §6.12 revised.
6 Replenishment engine REST? Mostly answered — likely UI-only; derive from VendorItem + Inventory_ByLocation
7 Lawn/garden module's custom fields on Item Mostly answered. Items have CATEG_COD + SUBCAT_COD (2-level), ATTR_COD_1 + ATTR_COD_2 (extensible attributes), MIX_MATCH_COD (mix-and-match group), ITEM_TYP (I/K/etc.), IS_TXBL, IS_FOOD_STMP_ITEM, ecommerce flags. Mix-and-match IS exposed via API as a code reference. Plant-specific custom fields likely use the attribute codes. Customer-level custom fields use 5×4 (alpha/code/date/number) profile slots enabled in CustomerControl.
8 Promotion stacking + effective-dating semantics ANSWERED — N/A. No Promotion endpoint exists; Module P is derived. See §6.11 revised.
9 Multi-company addressing strategy ANSWERED. <CompanyAlias>.<UserName> auth prefix; CRDM tenant_id × counterpoint_company_alias
10 Workflow / task in Counterpoint ANSWERED — NO. Module E not sourced from Counterpoint. See §6.13 revised.

New questions surfaced post deep-dive:

# Question Status
11 What is POST_NSPTransaction? ANSWERED. Endpoint to record secure-pay transactions from Monetra (a payment processor / gateway). Used by Counterpoint customers using Monetra. NSP = Non-Standard Payment. Resulting payments still appear as Document_Payments in normal Documents — Canary doesn't need to touch NSPTransaction directly.
12 What is GET_Workgroup? ANSWERED. Workgroup is a store / location grouping concept (multi-store coordination). Each workgroup has next-number generators for transactions, transfers, POs, etc. Carries THIS_LOC_ID, THIS_STR_ID, LOC_GRP_ID. NOT a labor workgroup. Useful for Module N hierarchy + multi-store deployments.
13 What does GET_Document payload look like? ANSWERED. See Brain/wiki/ncr-counterpoint-document-model.md. PS_DOC_HDR + 11 nested arrays (lines, payments, taxes, audit, etc.). Document is omnibus: covers sales, returns, voids, transfers, POs, RTVs, GFC.
14 What's in GET_CustomerControl? ANSWERED. AR_CTL record: aging-period config (4 periods + messages), customer-profile field enablement (5 each of alpha/code/date/number), loyalty-program system flag, statement settings. Does NOT define tiers; tiers are user-defined codes on the Customer record's CATEG_COD field.
15 Counterpoint Document type-code taxonomy Partially answered — at minimum: T (ticket/sale), XFER, RECVR, PO, PREQ, RTV, STC, EVENT, GFC, AR_DOC (inferred from Workgroup's next-number generators). Need to read additional sample payloads to confirm exact DOC_TYP code strings.

Status summary post 2026-04-25 deep-dive:

The SDD is sufficiently grounded for Phase 0–1 implementation. Remaining gaps surface during fixture-test development against an NCR sandbox.

12. Phasing dependencies + serialization gates

Phase 0 (foundation) ──┬─→ Phase 1 (T R F L N) ──┬─→ Phase 4 (A C Q)
                       │                          │
                       └─→ Phase 2 (P S) ─────────┘
                       │                          │
                       └─→ Phase 3 (D J) ──────────┘
                                                  │
                                                  └─→ Phase 5 (cutover)

Phases 1, 2, 3 can run in parallel after Phase 0 if multiple sessions / engineers are available. Phase 4 (especially Q — Loss Prevention) depends on Phases 1–3 outputs. Phase 5 depends on all prior phases.

Author: Senior ALX (laptop), 2026-04-25 Status: draft-1 — open questions remain; Phase 0 execution will surface answers to many Review gate: founder reviews before Phase 1 dispatch is written

Canary for NCR Counterpoint · GrowDirect LLC canary@growdirect.io