Skip to main content

Quick Start

This guide walks through the smallest possible end-to-end flow against the Shopper API: create a basket, scan an item, and finish the transaction. For the conceptual model behind these calls, see Business Flows and Architecture; for the full set of operations, see APIs.

Prerequisites​

  • A Hii Retail tenant, and a businessUnitId for the store you want to shop at.
  • A bearer token issued via Identity and Access Management / OCMS.
  • A barcode of a known item — one the configured Checkout Engine can resolve (see Unknown items).

Every request must include:

Authorization: Bearer <token>
Tenant-Id: <your-tenant-id>
Content-Type: application/json

Your First Basket​

1. Creating a basket​

POST /v3/baskets
{
  "customerId": "CUST123",
  "language": "en",
  "businessUnitId": "STORE001",
  "origin": "Android",
  "customerType": "Registered"
}

origin must be Android or iPhone. Omit customerId/customerType for an anonymous trip. The response returns the basketId you'll use for every following call, with basketState set to Started:

{
  "basketId": "BASKET789",
  "basketView": {
    "items": [],
    "price": { "grossPrice": 0, "netPrice": 0 },
    "totalItems": 0,
    "totalQuantity": 0,
    "activatedPromotions": []
  },
  "basketState": "Started",
  "attributes": {}
}

2. Scanning an item​

POST /v3/baskets/{basketId}/items
{
  "barcode": "5901234123457",
  "quantity": 2
}

The response returns the updated basket, now in the Shopping state:

{
  "basketId": "BASKET789",
  "basketView": {
    "items": [
      {
        "id": "ITEM001",
        "barcode": "5901234123457",
        "quantity": 2,
        "price": { "grossPrice": 9.99, "netPrice": 8.49 },
        "shortDescription": "Product Name"
      }
    ],
    "price": { "grossPrice": 19.98, "netPrice": 16.98 },
    "totalItems": 1,
    "totalQuantity": 2
  },
  "basketState": "Shopping",
  "ageVerificationRequired": false
}

A 422 response here means the item needs more input before it can be added — see Adding an item with packaging or Adding an item with quantity selection for how to handle it.

3. Finishing the basket​

POST /v3/baskets/{basketId}:finish

An empty body is enough for the simplest case. This kicks off checkout — which may include age verification or a rescan before the basket can be paid and finalized. See Business Flows for what can happen next, and Payment / POS Handover for how the trip is completed.

Where to Go Next​