Configure a Selfscanner
This guide covers a Selfscanner — a mobile or handheld app that shops via the Core Service's Shopper API — and how it configures itself against a given tenant and store. It doesn't cover device-level provisioning of the legacy My-Scan 5 handheld app (ADB, TerminalManager); that's a separate, older topic.
1. Fetch parameters at startup and cache them
The core mechanism a Selfscanner uses to configure itself is:
GET v3/parameters
(or GET v3/business-units/{businessUnitId}/parameters for a specific store)
Fetch this once at startup and cache it — don't poll. These parameters are static and not modifiable by a retailer through any live-updating mechanism: if a value changes on the server, the app needs to be restarted to pick it up. This is a deliberate design decision, not a limitation to work around — anything a retailer needs to change live is instead delivered through CCC and pushed over Socket.IO (see Configuration: Tenant Configuration), though no Selfscanner client consumes CCC-driven config today.
The response is a flat key/value map (Dictionary<string, string>), not a structured object — your client needs to know the specific keys it's looking for and read them out of that map, ignoring anything it doesn't recognize. In Cloud, this endpoint's response isn't scoped down to only "your app's" parameters — it reflects the tenant/store's broader resolved settings — so don't assume every key in the response is relevant to a Selfscanner.
2. What's in the parameter set
| Group | Parameters | Purpose |
|---|---|---|
| Barcode Definitions | Item (incl. date/weight-embedded variants), end-of-ticket/finish, cancel-basket, customer-card, force-rescan, hostess, command-server, wall, invalid, unknown (fallback), ConvertUPCAtoEAN13 | The patterns your client uses to classify a scanned barcode — see Business Flows: Item Scanning for how these fit into the scan flow |
| Ticket Processor Type | Online / Checkout Engine | Which ticket-processing mode the store runs |
| Rescan behavior | Postpone forced rescan (rescan at end-of-trip instead of immediately), full-vs-partial default, confirmation-mode timeout | Controls how your client should present a forced rescan — see Business Flows: Rescan |
| Promotions/display | Default language, media URI base path, discount-advertisement trigger mode, context-advertisement retrieval | Display/promotion behavior for your client's UI |
Payment-related settings (currency, country code, languages, tender type) are also part of what a tenant configures, but they're resolved separately at the tenant level rather than as part of this store-scoped set — see Configuration: Parameters and Integrate a Payment Provider rather than looking for them here.
3. Start shopping
Once configured, a Selfscanner is just another caller of the Shopper API — same auth model (bearer token + Tenant-Id, see Quick Start: Prerequisites), and origin (Android or iPhone) is mandatory when creating a basket. See Quick Start for the basic basket flow.
Reference
- Configuration: Parameters — how these parameters are set for a tenant/store, and how to add a new one.
- Quick Start — the basket operations a Selfscanner drives once configured.
- APIs — the full Shopper API reference.