Skip to main content

Transaction event integration

Integration phases​

The SCO publishes its transaction lifecycle to the AI Box over REST. It authenticates once to obtain an access token, then reports each transaction. The goal of this stage is simply that every event is sent correctly and accepted — validated across two environments, in order:

  1. Cloud — call the REST API against an Angible-provisioned instance on cloud. Contract-level testing, without hardware.
  2. Real AI Box device — the same partner code, now pointed at an Edge Device. Validates the SCO ↔ device path end-to-end.

The switch between them is just the target host (cloud instance IP → AI Box IP); the REST contract is identical.

Transaction lifecycle​

Every transaction opens with transaction-started and closes with transaction-completed. Most follow the normal checkout below; a customer who leaves without paying produces an abandoned checkout, which closes differently.

Normal checkout​

A transaction is built from two matched start/complete pairs, one nested inside the other — each must be both opened and closed:

  • Transaction — opened by transaction-started, closed by transaction-completed. Every call in between references its transaction ID.
  • Scan cycle — opened by scan-started, closed by scan-completed. It sits inside the transaction and can be re-entered any number of times.

The scan cycle can repeat — e.g. the customer returns from the payment screen to add more items, or the AI flags a missed item that has to be re-scanned.

Abandoned checkout​

When a customer walks away without paying, the SCO still closes the transaction cleanly — but it differs from a normal checkout in three ways:

  • transaction-completed carries status: checkout_abandoned instead of the normal completed status.
  • No scan-completed is sent. Completing the scan would trigger an AI check that isn't needed here, so the scan cycle is opened but never closed.
  • The next customer starts a brand-new transaction with a fresh transaction_id.

There is no Complete scanning step — that's the deliberate difference from a normal checkout. The status: checkout_abandoned on transaction complete is what tells the AI Box the cart was never paid for.

Notes on specific calls​

Most calls do exactly what their name says (Transaction Start, Transaction Complete, …). The ones below are worth a note:

  • Scan Start is re-entrant — scan-started is called again any time the SCO re-enters scanning after leaving it: when the customer backtracks from payment to add items, or when resolving an alert by rescanning.
  • Final prices — integrate one, not both. Both report the final checkout amount, used later to assess effectiveness (how much missed-scan loss the AI helped the merchant recover). They differ only in the key they update on:
    • PATCH /v1/events/{sco_id}/items — by item_id (matched to the item_id sent at item-added), one line per item. Recommended.
    • PUT /v1/{sco_id}/transactions/{transaction_id}/item-prices — by barcode (barcode + quantity + price). Use this when the SCO system can't express final prices as per-item lines (e.g. item1: $100, item2: $0) and must aggregate by barcode instead.