Skip to main content

SCO screens & API calls

This walks a transaction through the SCO's screens and shows which REST event each screen sends to the AI Box.

Authentication​

Before sending any transaction events, the SCO authenticates once to obtain an access token:

  1. Call POST /v1/events/{sco_id}/device-register with the device's client_id and client_secret.
  2. The response returns an access_token, valid for 24 hours.
  3. Send it as the token header on every subsequent call. If a call that was working starts returning 403, the token has expired — call device-register again to get a fresh one.

See the Edge API reference for the full Device Register request and response.

Screens​

note

The screens are a generic reference, not a prescribed design — your real UI is your own. What matters is the calls each step makes, which are the same across vendors. See the Edge API reference for each call's request and response.

Welcome
Touch to start — scan your first item to begin
Start
Customer

Start screen — a customer begins

The SCO shows its landing screen. When a customer starts a checkout, the SCO opens a new transaction; every later call references its transaction ID.

Call APIs
  • POST /v1/events/{sco_id}/transaction-started
Item 1$2.20
Item 2$1.80
Item 3$3.10
Total$7.10
Pay
Customer

Scanning page

Opening the scanning page starts the scan cycle. Each item the customer scans or removes is reported.

Call APIs
  • POST /v1/events/{sco_id}/scan-started — scanning page opens
  • POST /v1/events/{sco_id}/item-added — each item scanned
  • POST /v1/events/{sco_id}/item-removed — an item removed
Item 1$2.20
Item 2$1.80
Item 3$3.10
Total$7.10
PayGet Help
Customer

UI state change

The SCO reports UI state changes as they happen, independent of the scan cycle. Tapping Get Help turns staff mode on (shown here); it turns off again when staff dismiss it. A state change also fires when the transaction goes idle for a set period — the customer may have already left the SCO.

Call APIs
  • POST /v1/events/{sco_id}/states — e.g. staff mode on when Get Help is tapped
Item 1$2.20
Item 2$1.80
Item 3$3.10
Total$7.10
Checking your items…
Please wait
Customer

Tap Pay — complete the scan

When the customer taps Pay, the SCO completes the scan cycle. This is what triggers the AI Box to run its check and report any unscanned items (returned later as an MQTT alert).

Call APIs
  • POST /v1/events/{sco_id}/scan-completed — triggers the AI check
Item 1$2.20
Item 2$1.80
Item 3$3.10
Total$7.10
Please select a method of payment
CashCard
Customer

Payment page

After the scan is verified, the customer selects a payment method. The SCO reports the final checkout amount here. Integrate one of the two final-price calls, not both.

Call APIs
  • PATCH /v1/events/{sco_id}/items — final prices by item_id (recommended)
Item 1$2.20
Item 2$1.80
Item 3$3.10
Total$7.10
Payment complete
Thank you!
Customer

Thank you page

Payment is complete. The SCO finalizes and closes the transaction.

Call APIs
  • POST /v1/events/{sco_id}/transaction-completed — close the transaction