Skip to main content

My-Scan

Shopper API​

1. Overview​

My-Scan is a complete solution for self-scanning or self-service. It supports the full shopping journey, from the normal in-store shopping trip to final checkout. During shopping, it handles communication with mobile or handheld scanning devices, manages basket activity, applies business rules, and connects with backend systems like price engines and monitoring services. At checkout, it does all ticket-related processing, enabling baskets to be downloaded, validated, uploaded for self-service analytics, and finalized while preventing invalid actions such as checkout during an active payment state.

2. Basket Flow​

In My-Scan, the basket flow starts when a shopper session creates or opens a shopping basket, usually from a mobile or handheld scanner. Items are then added, updated, or removed as the customer scans products, while the service validates each action, applies pricing/business rules, and keeps the basket state synchronized. When shopping is complete, the basket moves to checkout: it is validated, prepared for ticket/payment handling, and locked against invalid changes during payment. After successful completion, the basket is finalized and reported/uploaded to the relevant backend or analytics services.

3. Basket States​

The basket follows a simple shopping lifecycle: it starts as NotInitialized, moves through Starting while a new shopping trip is being created, and becomes Started once the basket is ready but still empty. When the customer scans the first item, the basket enters Shopping, where items can be added or removed during the normal shopping trip. When the customer proceeds to checkout, the basket moves to Finishing, and once checkout/finalization succeeds, it reaches Finished.

4. Basket View​

BasketView is the reader-facing representation of a shopper’s current basket. It contains the information needed by the app, scanner, or checkout UI to display and validate the shopping session.

It contains:

  • Items the list of products currently in the basket, including product descriptions, prices, deposit, age limitations, and discounts applied.
  • Price the basket totals, such as the calculated amount to pay (the net price).
  • TotalItems the number of item lines added to the basket, or the number of separate items.
  • TotalQuantity the combined quantity of all items in the basket.
  • ActivatedPromotions promotions or discounts that have been applied at basket level.

In short, it is the customer-facing snapshot of the basket: what has been scanned, how many items it contains, what it costs, and which promotions are active.

BasketView will usually combine items when possible, but this is configurable: it is also possible to have the last scanned item always in the same position. When combining items, there will be several special cases, for example barcodes with weight or price information will be on separate lines. For GS1 digital links, when the GTIN is the same the items will be combined.

5. Supported Barcodes​

My-Scan supports many retail barcode formats, depending on the capabilities of the configured price engine. It may support EAN13, EAN8, UPC-A, UPC-E, PLU codes, and GS1 Digital Links.

6. Registered vs Anonymous Shoppers​

My-Scan supports both shopping trips for registered and anonymous shoppers. Registered shoppers will be validated before starting a shopping trip (is self-service allowed for this shopper?).

7. Payment Integration​

My-Scan supports direct payment processing for mobile devices through the Softpay app. The ticket can also be downloaded by a POS or SCO for payment.

8. Order of Operations​

Creating a Basket​

A typical basket begins with the Create operation. Once the basket is created, the customer can commence scanning and adding items to the basket.

Every Create operation requires a mandatory origin. This represents the device type from which the basket is created. It can be set with one of the following values:

  • Android
  • iPhone

The Create operation returns a basketId which will be required for any subsequent operation. The Create operation returns basket state Started.

Adding an Item​

Adding an item requires an item barcode and the basket identification (basketId). Providing a quantity is optional. If no quantity is provided, the quantity will be one. Providing packaging is also optional, unless packaging is required for the item. Note: It is only possible to add items to a basket if the basket is in one of the following states: Started, Shopping.

The item, when recognized, will be added to the basket and be displayed in the basket view. Sometimes more than one item can be the result of a single Add operation, for example an additional free promotion item. Also, when applying promotions, prices on several basket view items may change.

Adding an item with packaging to the basket​

In case of unspecified packaging information and quantity, a PackagingRequired message is returned (status code: 422) together with AvailablePackagings and item details. In this case the item should be added with a selected packaging from the AvailablePackagings.

Adding an item with an age limitation to the basket​

If the product has an age limitation for the shopper age, for example when buying alcohol products, the attribute AgeRequired in the returned item will indicate the age that a shopper should have for purchasing this item. A value of zero means there is no age restriction.

Adding an item with quantity selection​

If the product is an "AskQuantity" item, the response will have a 422 status code and the item in the response will have the attribute "askQuantity" set. A selection dialog should be presented to the shopper to select the quantity. The next call should have the same barcode, but also include the selected quantity.

Retrieving last added item​

The add item operation response contains the property "AddedItem" which exposes the newly added item. In cases where the item is visible the Add operation will also return the "AddedItemView" with the viewItemId.

Updating the quantity​

There are three ways to update the quantity of an item in the basket.

  • Decrement the quantity by one (only when greater than 1)
  • Increment the quantity by one
  • Update the quantity to a chosen value (idempotent)

These operations require an existing viewItemId as returned in the BasketView. Updating the quantity is only possible when the state is Shopping.

Removing an item​

Removing an item from the basket can be done by calling DELETE on a given viewItem. It requires a viewItemId returned in the basket view. This completely removes the complete line from the view. If the quantity of that line was 5, it will actually remove 5 items. If the goal is to just decrement the quantity by one, call Decrement. Removing an item is only possible when the state is Shopping.

Getting a Basket​

Retrieving a basket is possible by calling GET on the basketId. This is just for completeness, since the BasketView is already returned by other operations as well.

Cancelling a Basket​

Once a basket is started, it can be canceled by calling DELETE on a basketId. The cancel basket operation removes the active basket and the basket can no longer be finished. Cancelling a basket is possible when the state is Started or Shopping.

Finishing a Basket​

When the shopper wants to finish, he typically scans an End-Of-Trip (EOT) barcode (but this can also be done in other ways). It is possible to finish a basket with the finish operation on basketId. Finishing a basket is only possible when the state is Started, Shopping, or Finishing. Finishing starts the checkout process, including a possible validation (audit or rescan) and payment (via a POS or payment service).

The Finish operation can have:

  • a "rescanRequired" flag. When set, a rescan will always happen. This is possible in a scenario when the device is owned by the store and handed over to a store employee before actually finishing the shopping trip.
  • an "assistanceRequested" flag. When set, the shopper asks for assistance from a store employee, for example when unable to scan an item.
  • an "eotBarcode" with the scanned EOT barcode with more details about the finish operation, such as if rescans should start on another device.
RescanMessage and RescanRequired​

The Finish operation can end up with a rescanMessage or rescanRequired flag when the shopper is selected for rescan. RescanMessage means the shopper is selected for rescan but the rescan will start on another device. When the shopper uses its own mobile device, this is the standard. RescanRequired means the shopper is selected for rescan and the rescan will start on the same device. When the shopper uses a device owned by the store, this is possible.

TransferredBasketId​

The TransferredBasketId property can be used to transfer the basket to another application which can then start the rescan process.

Retry Finishing a Basket​

When finishing a basket it is possible for the payment to fail. In this situation, a retry finish basket operation is needed since the basket is already in a Finished state.

9. Parameters​

An endpoint is available to retrieve various parameters, such as barcode definitions.

POS API​

1. Download​

After completing a shopping trip, the final ticket can be downloaded by a POS or SCO for payment. The download operation will return the ticket information, including the items, prices, and any applied promotions, as well as the total amount to be paid. This allows the POS or SCO to process the payment and finalize the transaction.

2. Upload​

After completing the payment, the POS or SCO will upload the ticket information to the backend system. This allows the backend system to process the ticket and generate any necessary reports or analytics.