Smart Retail Counter API Quick Start

This quick start reads a store’s figures from a Smart Retail Counter box. You need curl and about ten minutes. The numbers in the answers below are sample values. Counting is anonymous: the API gives no identity and no image.

Before You Start

Ask an admin of the box to create an API account on the dashboard (API accounts page) with:

• the role Viewer on the store’s site;
• the scope read (add export to download the log as a file);
• an expiry date.

They give you the token (<API_KEY> below), the box’s address (<BOX_HOST>) and a copy of the box’s certificate (box.pem, from Download the box’s certificate on the API accounts page) with its SHA-256 fingerprint: check it as The Box’s Certificate shows. Authentication and Scopes explains each of these.

Find Your Site

curl --cacert box.pem \
  -H "Authorization: Bearer <API_KEY>" \
  "https://<BOX_HOST>/api/v1/sites"

{
  "items": [
    {
      "id": 1,
      "name": "North Plant",
      "timezone": "Asia/Jakarta",
      "created": "2026-10-01T02:00:00Z",
      "version": 4,
      "my_role": "viewer",
      "location": { "lat": -6.2, "lon": 106.8 },
      "area": null,
      "zones": 3
    }
  ]
}

Keep the site’s id (here 1).

Read The Store Overview

Ask for one period with from and to (RFC 3339; %2B is the + of the time zone offset):

curl --cacert box.pem \
  -H "Authorization: Bearer <API_KEY>" \
  "https://<BOX_HOST>/api/retail/v1/sites/1/overview?from=2026-11-01T00:00:00%2B07:00&to=2026-11-02T00:00:00%2B07:00"

{
  "entries": 1284,
  "exits": 1241,
  "passersby": 5310,
  "capture_rate": 19.5,
  "visits": 1190,
  "engaged_rate": 41.3,
  "checkout_rate": 28.7,
  "avg_dwell_min": 11.4,
  "conversion": { "value": 24.1, "source": "pos", "transactions": 309 },
  "in_store_now": 37,
  "queues_now": [
    { "zone": "Checkout", "length": 4, "est_wait_s": 95, "at": "2026-11-02T10:58:00Z", "long_queue_length": 6 }
  ],
  "repeat_share": null,
  "vip_visits": 0,
  "demographics": {
    "cells": [{ "age_band": "25-34", "gender": "female", "visits": 214, "share": 22.3 }],
    "unknown_visits": 231
  },
  "occupancy_limit": 120,
  "long_queue_length": 6,
  "store_hours": { "open": "10:00", "close": "22:00" }
}

Field	Meaning
entries, exits, passersby	People who came in, went out and walked past the door in the period
capture_rate	Entries as a percentage of entries and passersby
visits, avg_dwell_min	Visits in the period and their mean length in minutes
engaged_rate, checkout_rate	The percentage of visits marked engaged, and of visits that reached the checkout
conversion	With POS data (pos): transactions as a percentage of entries; without it (checkout_estimate): the checkout rate
in_store_now, queues_now	People in the store now, and each queue zone’s latest length and estimated wait
demographics	Visits per age band and gender

Percentages are 0 to 100 and null when there is nothing to divide by. For the same figures per hour or day, call GET /api/retail/v1/sites/1/trend; per zone, GET /api/retail/v1/sites/1/zones; queues per hour, GET /api/retail/v1/sites/1/queues.

Read The Visitor Log

curl --cacert box.pem \
  -H "Authorization: Bearer <API_KEY>" \
  "https://<BOX_HOST>/api/retail/v1/sites/1/logs?from=2026-11-01T00:00:00%2B07:00&to=2026-11-02T00:00:00%2B07:00&limit=50"

{
  "items": [
    {
      "id": "31:7712",
      "entered": "2026-11-02T10:31:02Z",
      "exited": "2026-11-02T10:44:40Z",
      "dwell_s": 818,
      "engaged": true,
      "reached_checkout": true,
      "age_band": "25-34",
      "gender": "female",
      "repeat_visitor": null,
      "entry_line": "Main door",
      "cameras": [31, 32],
      "zones": [{ "zone": "Aisle 2", "kind": "display", "dwell_s": 240 }]
    }
  ],
  "next_before": "2026-11-02T10:31:02Z"
}

Each row is one anonymous visit. For the next page, send next_before as before. Download the period as a file with GET /api/retail/v1/sites/1/logs/export?format=csv and the scope export.

Send POS Transactions

The conversion rate uses the store’s own transaction counts. Your POS can send them per interval in two ways:

• signed by the POS itself: POST /api/retail/v1/pos/{site}, with the site’s POS key made by an admin of the site on the dashboard (see Signing Requests to the Box);
• as a CSV upload with an API token that is an admin of the site: POST /api/retail/v1/sites/1/pos/upload (start,end,transactions).

Next Steps

• Push visits, door crossings, queue samples and the floor’s dwell time to your system instead of polling: Webhooks (event types retail.visit, retail.crossing, retail.queue, retail.floor and, with personal_data, retail.vip, and periodic summaries).
• Every operation and field: Smart Retail Counter API reference and platform API reference.