API

RetailNext has an extensive API for users to access and modify data in the RetailNext cloud service and integrate them with other existing systems.

The API calls are REST compliant and make use of the most common HTTP methods such as GET and POST, with the data sent and received in JSON format. All requests require HTTPS connections and authentication with API keys.

This page details the most recent API methods available, while old methods are listed at Deprecated APIs.

For help with using this page, more examples, and frequently asked questions; visit Getting Started with the API.

Please review our API Implementation Considerations before building or integrating applications with the RetailNext API.

Authentication

All API endpoints are authenticated using your API token over HTTP basic auth. API tokens have a unique Access Key and Secret Key that are used during API authentication.

Subscription Admins can issue and manage API tokens for their subscription from the RetailNext cloud interface in Admin Settings > System Access Tokens. Visit System Access Tokens to learn more.

Authentication Header

--basic --user <AccessKey>:<SecretKey>

Pagination

 

Version 1 API

All API v1 responses have a default and maximum page length limit of 100 entries. Queries with more items than the page length limit will have responses split across multiple pages.

Parameters

X-Page-Length

integer

default: 100

If included, the response page length will match the specified value.

The maximum page length is 100.

X-Page-Start

integer

If included, the response will start at the specified value.

This is typically used to retrieve subsequent pages for queries that exceed the page length limit.

Example Request

curl -viL --basic --user <AccessKey>:<SecretKey> \ -H "X-Page-Length: 20" \ "https://<subscription>.api.retailnext.net/v1/location"

Example Response

HTTP/2 206 content-type: application/json ... x-frame-options: SAMEORIGIN x-page-next: 20 ...

Example Request: Subsequent Pages

The HTTP response code indicates whether a response contains all possible entries, or if you need to fetch more pages; whereby:

  • 200: OK (no additional pages)

  • 206: Partial Content

Fetch the next page by adding X-Page-Start to your original request header with a value that matches X-Page-Next from the previous response.

Version 2 API

API v2 methods do not support pagination and have a limit of 10,000 entries per response.

If you expect a large response that may get trimmed by this limit, be more specific in your query, e.g. use additional filters.

Locations

 

Request Limits

Concurrent location requests are limited to 2 per customer subscription.

Query Locations

Returns locations and related fields.

POST https://<subscription>.api.retailnext.net/v2/location

Example Request

This example filters for only store type locations and includes extra fields for store_id and occupancy_limit

Where the request.json file contains:

Example Response

Extra Fields and Filtering

As in the example above, you can specify extra fields in your query to include additional location fields that are normally not returned in responses. The supported options are as follows:

  • store.time_zone

  • store.store_id

  • store.pos_id

  • store.pos_division_id

  • store.staff_hour_id

  • store.occupancy_limit

  • store.validated_address

Specify where clause to filter the results. This is particularly useful when normal responses exceed the API pagination limit. The available options in where clause and their filters are:

  • location_types

    • display

    • entrance

    • fitting_room

    • other

    • store

    • region

  • node_types

    • location

    • video

    • traffic

    • pos

Besides where clause, root_uuids is also available to get the list of all sub-locations/nodes under a certain location. E.g.:

Create Locations

Creates sublocations and regions.

POST https://<subscription>.api.retailnext.net/v2/location/create

Parameters

name*

string

The name of the location

parent_UUID*

string

The UUID of the parent store or region

location_type*

string

Supported sublocation types: entrance, fitting_room, display, other

Supported region type: region (parent UUID must be another region)

area

integer

The area in square feet (only applicable to sublocations)

aggregate_to_parent

boolean

default: true when "entrance", false otherwise

true, false (only applicable to sublocations)

aggregate_to_store

boolean

default: true when "entrance", false otherwise

true, false (only applicable to sublocations when floor level conversion is enabled)

* required parameter

  • Creating store locations is not supported through the API

  • To create a region under the top-level parent, or the "Organization" level, you must set the parent_uuid value to that of the subscription UUID. Contact RetailNext support if you need help obtaining this value.

  • After creating a location, the API response includes the UUID of the newly created location to use in further API operations

Example Request

This example creates a new Display sublocation type within a store.

Where the request.json file contains:

Example Response

Update Locations

Update location fields.

PUT https://<subscription>.api.retailnext.net/v2/location/<location_uuid>

Parameters

name

string

Name of location

parent_UUID

string

Moves the location beneath the specified parent location

location_type

string

Supported sublocation types: entrance, fitting_room, display, other

area

integer

Area in square feet (only applicable to stores and sublocations)

occupancy_limit

integer

Occupancy limit (only applicable to stores)

bandwidth_limit_kilobits_per_second

integer

Custom outbound bandwidth limit of a store (only applicable when global bandwidth limits are enabled)

Sending a value of 0 clears any existing custom store limit and reverts its value to the global limit.

aggregate_to_parent

boolean

true, false (only applicable to sublocations)

aggregate_to_store

boolean

true, false (only applicable to sublocations when floor level conversion is enabled)

  • Changing the location_type to or from “store” or “region” is not supported (in other words, you can only change the location_type of sublocations).

Example Request

This example updates a store by changing its name, area and occupancy limit; as well as moving it to a new parent region.

Where the request.json file contains:

Example Response

Updating Locations in Bulk

You can update a bulk selection of locations to a specified parameter value in certain situations.

This example updates the respective occupancy limit parameter of multiple store locations.

Where the occupancy_limit.csv file contains:

Point of Sale

Integrate point of sale data via API.

Request Limits

Concurrent POS upload requests are limited to 10 per customer subscription. There is also a limit of 1,200,000 transaction uploads per day per subscription. Moreover, one API request can contain up to 20 transactions, as the API is not intended to be used for bulk uploads. Refer to the Point of Sale Upload for CSV options.

Upload Transactions

POST https://<subscription>.api.retailnext.net/v1/pos/transaction

Parameters

See for the full list of parameters. The parameters provided via the API should correspond with those configured on the Admin Settings > File Upload Configuration > POS page.

Example Request

Where the request.json file contains:

Example Response

Query Single Transaction Status

GET https://<subscription>.api.retailnext.net/v1/pos/transaction/status/<transaction-uuid>

Example Request

Example Response

Query Multiple Transactions Status

Query the status of all transactions uploaded in the last 24 hours.

GET https://<subscription>.api.retailnext.net/v1/pos/transaction/status/

Example Request

Example Response

Status API allows filtering by status and duration:

  • Append ?status=rejected or ?status=processed to get the list of all transactions by status in the past 24 hours: https://<subscription>.api.retailnext.net/v1/pos/transaction/status?status=rejected

  • Query all transactions status in a specific duration using start_time and end_time https://<subscription>.api.retailnext.net/v1/pos/transaction/status?start_time=2022-07-11T10:00:00-01:00&end_time=2022-07-11T21:59:59-01:00

  • Status and Duration filters can also be specific together in a single request: https://<subscription>.api.retailnext.net/v1/pos/transaction/status?start_time=2022-07-11T10:00:00-01:00&end_time=2022-07-11T21:59:59-01:00&status=rejected

Store Hours

Query Store Hours

Returns store hours within specified parameters.

POST https://<subscription>.api.retailnext.net/v1/storehours

Parameters

stores*

string

UUID of store location

start_date*

ISO 8601

Start date in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ)

end_date*

ISO 8601

End date in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ)

* required parameter

Example Request

Where the request.json file contains:

Example Response

Datamine

Query Metrics

Returns metrics within specified parameters.

POST https://<subscription>.api.retailnext.net/v2/datamine

Parameters

locations*

string

UUID of location

metrics*

string

See Metrics Glossary for API identifiers

date_ranges*

string

from and to in conjunction with additional objects.

See More Details on Date Ranges below

time_ranges*

string

from and until in hh:mm, or,

type: store_hours

group_bys*

string

time, date, location and day_of_week

See More Details on Group Bys below

* required parameter

Example Request

This example queries Traffic In & Out metrics for last week during store hours, with the response grouped by one day.

Where the request.json file contains:

Example Response

More Details on Date Ranges

The date_ranges parameter determines the dates from and to, respectively, for which to datamine. It also requires the use of additional objects, being:

  • name

  • gregorian

  • absolute

  • relative.

Date Ranges options

Name

The name key supports simple named date values, such as now and today.

Example Request

Where the request.json file contains:


Gregorian

The gregorian key supports Gregorian calendar date values in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ), where “Z” implies that the time zone is UTC.

Example Request

Where the request.json file contains:


Absolute

The absolute key supports various date pairs with integer values.

Example Request

Where the request.json file contains:

Supported Options
Date Examples

Relative

The relative key supports flexible time-based strings in relation to another specified date, usually used in conjunction with other date options.

If a base date isn’t specified, any relative date specification is considered to be in relation to the opposing date range parameter, being from or to respectively. See Mixed Options below for more details.

Example Request

Where the request.json file contains:

Supported Options

Mixed Options

You can use a mix of any two options in from and to date range specifications, respectively.

For regularly repeated API requests, relative date ranges are commonly used in conjunction with another option.

Example Requests

Date range for June, 2020 plus 4 months - the request.json file contains:

Date range for last week - the request.json file contains:

Date range for current month-to-date - the request.json file contains:

Date range for the last 24 hours - the request.json file contains:

More Details on Group Bys

The group_bys parameter determines how the data is sliced, or grouped, in the response. It supports one or more layers of the following group keys:

  • time

  • date

  • location

  • day_of_week

Each group is then further associated with a unit and value according to specification.

Group Bys options

Example Requests

Single Grouping by date - the request.json file contains:

Layered Grouping by location, then time - the request.json file contains:

Supported Options

Occupancy

 

Query Occupancy

Returns current occupancy metrics.

POST https://<subscription>.api.retailnext.net/v2/datamine

Example Request

This example queries for the current occupancy of the store location dace69f6-b307-11e9-819d-0000698cf233.

Where the request.json file contains:

Example Response

The query results in traffic_out of 5 and traffic_in of 4, so the total_occupancy is 1. Note that the query was grouped by location, so the result includes the name of the store.

Time Zones

Current Occupancy requests use "name" date range specifications, meaning that you must provide a time zone in the query. To request metrics with timestamps that match up with that of a store’s local timezone, use the local timezone of that store in your query.

Additional time zone flexibility is provided specifically for occupancy queries. See the examples below for more information.

With Time Zone

Obtain the time zone of a location using /v2/location.

Example Request

In the example request below, dace69f6-b307-11e9-819d-0000698cf233 is the store location.

Example Response

Update Occupancy

Update occupancy by a specified adjustment value.

POST https://<subscription>.api.retailnext.net/v1/occupancy/adjust

Parameters

store_uuid*

string

UUID of store location

adjustment_count*

integer

Occupancy adjustment value.

Supports negative or positive values, but must be non-zero.

adjustment_date

ISO 8601

Occupancy adjustment date/time in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ).

If omitted, the current time in store local time zone will be used instead.

* required parameter

Example Request

Where the request.json file contains:

Users

 

Query Users

Returns users and related fields.

GET https://<subscription>.api.retailnext.net/v1/users

Example Request

Example Response

Filtering

By appending the URL, you can filter your response to only include users with a specified parameter’s value.

Filtering examples

Type

If you have SSO enabled, you can append your query to only include local or SSO users, respectively. The example below queries for SSO users only.

Email

The example below queries for users with an email address that exactly matches storemanager@domain.com

Create Users

Creates an SSO user account.

POST https://<subscription>.api.retailnext.net/v1/users

Parameters

email*

email address

User email address

type*

string

Type of user account.

Only sso value accepted.

name

string

default: <user_email>

User name

disabled

boolean

default: false

User disabled status

user_profile_id**

string

UUID of User Profile

location_profile_id**

string

UUID of Location Profile

location_ids**

string

UUID of Location. Interchangeable with location_profile_id.

See Custom Locations for details.

* required parameter

** conditionally required parameter

Example Request

Where the request.json file contains:

Example Response

Update Users

Update the permissions of a user.

PUT https://<subscription>.api.retailnext.net/v1/users/<user_uuid>

Parameters

user_profile_id

string

UUID of User Profile

location_profile_id

string

UUID of Location Profile

location_ids

string

UUID of Location. Interchangeable with location_profile_id.

See Custom Locations for details.

Example Request

Where the request.json file contains:

Example Response

Custom Locations

Update explicitly authorized locations of a user, instead of a predefined location profile.

To specify custom locations replace the key location_profile_id with location_ids, then list the UUIDs of permitted locations.

Example Request

Where the request.json file contains:

Example Response

User Profiles

Query User Profiles

Returns user profiles and related fields.

GET https://<subscription>.api.retailnext.net/v1/user_profiles

Example Request

Example Response

Location Profiles

Query Location Profiles

Returns location profiles and related fields.

GET https://<subscription>.api.retailnext.net/v1/location_profiles

Example Request

Example Response

Health Monitoring

Query Health Alerts

Returns health alerts and related fields.

POST https://<subscription>.api.retailnext.net/v1/healthalerts

Parameters

start_time

ISO 8601

Alerts created before a date/time in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ)

Example Request

Where the request.json file contains:

Example Response

Response Fields

All Health Monitoring API response fields are a subset of the same fields provided by Automated Systems notification emails. Visit Health Monitoring Emails > Notification to Automated Systems for a list of field descriptions.

File Upload Status

Returns status of uploaded files. See for more details.

Predicted Traffic

Request Limits

Concurrent predicted traffic requests are limited to 3 per customer subscription.

Query Predicted Traffic

Returns predicted traffic metrics within specified parameters.

POST https://<subscription>.api.retailnext.net/v1/predictedtraffic

Parameters

store_uuid*

string

UUID of store location.

Supports one entry per query.

first_day*

date

First day in yyyy-mm-dd.

Must be in the future.

last_day*

date

Last day in yyyy-mm-dd.

Must be in the future.

* required parameter

Example Request

Where the request.json file contains:

Example Response

Zone Transitions

Query Zone Transitions

Returns FPA zone transition metrics within specified parameters.

POST https://<subscription>.api.retailnext.net/v1/zone_transitions

Parameters

locations*

string

UUID of location

date_ranges*

string

"start" and "finish" paired with respective date values in yyyy-mm-dd

metrics

string

default: all

"all", "employee" and "customer"

transitions

string

default: direct_only

"direct_only", "direct_and_indirect" and "directionless"

dwells

string

default: dwells_only

"dwells_only", "non_dwells" and "all_traffic"

time_ranges

string

default: store_hours

"start" and "finish" paired with respective time values in hh:mm, or, "type": "store_hours"

days_of_week

string

default: all days of week

"monday", "tuesday", "wednesday", "thursday", "friday", "saturday" and "sunday"

* required parameter

Example Request

This example queries Traffic In & Out metrics for last week during store hours, with the response grouped by one day.

Where the request.json file contains:

Example Response

FPA Zones

Query FPA Zones

Returns FPA floorplans and related fields.

GET https://<subscription>.api.retailnext.net/v1/fpafloorplans

Example Request

Example Response

Response Fields

Field

Sample Values

Description

Field

Sample Values

Description

id

f64b51ac-546f-11eb-9441-8000514932de

UUID of floorplan or zone

name

API Store Floorplan

Name of floorplan or zone

store_id

aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9

UUID of store location

store_name

API Store

Name of store

type

fpa / staff / mask

Type of zone. Kinetic Map Masks are excluded.

location_id

24f99a38-5478-11eb-98ec-40002ded88bc

UUID of a zone’s parent location

location_name

Table 1

Name of a zone’s parent location

area

46907.56

Size of the zone location in square centimeters

dwell_time_threshold_ms

10

Minimum amount of time a shopper must linger in a zone before registering a dwell event, defined in milliseconds

zone_threshold_mm

1000

Size of the zone’s configurable buffer area for track detection and metrics collection, defined in millimeters

x

1751.2620277487956

X coordinate of a point of the zone relative to the overall floor plan, defined in centimeters

y

384.9399262748038

Y coordinate of a point of the zone relative to the overall floor plan, defined in centimeters

Inventory

 

Request Limits

Concurrent camera requests are limited to 3 per customer subscription.

Query Cameras

Returns camera hardware and related fields.

GET https://<subscription>.api.retailnext.net/v1/inventory/cameras

Example Request

Example Response

Response Fields

Field

Sample Values

Description

Field

Sample Values

Description

analytics: direction_line_configured

true / false

True if a direction line is configured on the device

analytics: dwell_zone_count

0, 1, 2, ...

Number of dwell zones configured on the device

analytics: traffic_line_count

0, 1, 2, ...

Number of traffic lines configured on the device

appliance_id

97f59a38-5478-11eb-98ec-40002ded88ty

UUID of appliance to which the device is connected

configuration_summary: device_name

Entrance

Name of device (Brickstream sensors only)

configuration_summary: sensor_group

Brooklyn, NY

Name of device location (Xovis sensors only)

configuration_summary: sensor_name

Entrance

Name of device (Xovis sensors only)

configuration_summary: site_name

Brooklyn, NY

Name of device location (Brickstream sensors only)

device_id

20:C3:13:0F:1D:2A

MAC address of the device

device_name

Back Entrance

Name of device

height

3860

Configured height of device, defined in millimeters (Aurora only)

last_heard

2020-01-14T22:30:18.363Z

Timestamp of the last communication from the device to the RetailNext cloud service

model

Aurora

Model of device

network_configuration: dns

8.8.8.8

Local static configuration of device DNS

network_configuration: gateway

192.168.1.1

Local static configuration of device Gateway

network_configuration: ip

192.168.1.15

Local static configuration of device IP address

network_configuration: mode

0, 1

Local network configuration of device, DHCP (0) or Static (1)

network_configuration: ntp

pool.ntp.org

Local static configuration of device NTP

private_ip

192.168.1.15

Local Area Network IP address of device

public_ip

73.181.6.188

Public IP address of device

serial_number

15290487

Serial number of Xovis or Brickstream device

store_uuid

a434a682-30a0-11ea-896a-00005f259c6e

UUID of store location to which the device is assigned

type

0, 1, 2

Device type: (0) Monocular camera, (1) Aurora, (2) Xovis, Brickstream

vendor

RetailNext, Xovis, Brickstream, Axis

Device Vendor

video_channel_count

0, 1, 2, ...

Number of video channels configured for device

video_channel_uuids

9290bc70-3480-11ea-81c9-c000c7e8079f

UUID of video channels configured for device

Query Channels

Returns video channels and related fields.

GET https://<subscription>.api.retailnext.net/v1/inventory/channels

Example Request

Example Response

Response Fields

Field

Sample Values

Description

Field

Sample Values

Description

blur_video

true / false

True if video blurring is enabled on the device

channel_uuid

9290bc70-3480-11ea-81c9-c000c7e8079e

UUID of the video channel

device_id

92710a06-3480-11ea-9877-40003d3dd9a9

UUID of device producing the video channel

frame_rate

10

Video recording quality setting for frames per second (fps)

name

Registration Desk

Configured name of video channel

recording_enabled

true / false

True if recording is enabled for the video channel

record_on_motion

true / false

True if recording on motion is enabled for the video channel

resolution

1280x960

Video recording quality setting for resolution

snapshot_enabled

true / false

True if high resolution snapshots are enabled for the video channel

snapshot_interval_secs

300

Configured time interval between snapshots, defined in seconds

snapshot_resolution

1400x1050

Snapshot quality setting for resolution

Query Appliances

Returns appliance hardware and related fields.

GET https://<subscription>.api.retailnext.net/v1/inventory/appliances

Example Request

Example Response

Response Fields

Field

Sample Values

Description

Field

Sample Values

Description

appliance_id

323231f8-6afg-11eb-8684-4000fc072082

UUID of appliance

mac_address

00:0D:29:60:FB:CB

MAC address of appliance

network_configuration: dns

8.8.8.8

Local static configuration of appliance DNS

network_configuration: gateway

192.168.1.1

Local static configuration of appliance Gateway

network_configuration: ip

192.168.1.15

Local static configuration of appliance IP address

network_configuration: mode

0, 1

Local network configuration of appliance, DHCP (0) and Static (1)

network_configuration: ntp

pool.ntp.org

Local static configuration of appliance NTP

private_ip

192.168.1.15

Local Area Network IP address of appliance

public_ip

73.181.6.188

Public IP address of appliance

store_uuid

af21ffd8-9e2c-11e5-9bc9-0e5ba9bee1b9

UUID of store location to which the appliance is assigned

Video Export

 

Start Export

Starts a video export within specified parameters.

POST https://<subscription>.api.retailnext.net/v1/video/export/start

Parameters

channel*

string

UUID of video channel

Provide multiple channel parameters to include up to 16 total video channels from the same store appliance.

When multiple channels are specified, you may also provide a resolution parameter to determine the resolution of the video.

The default resolution is 1024x768.

start*

ISO 8601

Export start date/time in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ)

end*

ISO 8601

Export end date/time in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ)

analytics_overlay

boolean

default: 0

0, 1; where 1 enables analytics overlays (tracks, traffic lines, zones and other analytic shapes)

info_overlay

boolean

default: 0

0, 1; where 1 enables information overlays (video channel name and date/time)

raw

boolean

default: 0

0, 1; where 1 enables raw video.

Raw video exports are only necessary for troubleshooting, as they are much larger and may not work with some software.

* required parameter

Example Request

Example Response

Query Export Status and Download

Returns the current status of a video export and, if ready, the download link.

GET https://<subscription>.api.retailnext.net/v1/video/export/task/<export_id>

Example Request

Example Response

Video Stream

 

Generate Token

Returns a token to stream a video channel over HLS.

POST https://<subscription>.api.retailnext.net/v1/hlsapitoken

Parameters

location_uuid*

string

UUID of location.

The generated token provides access to video channels within the specified location.

* required parameter

Example Request

Where the request.json file contains:

Example Response

Stream Video

Using a generated token value, create an HLS M3U8 playlist to stream a video channel in the URL format below.

The URL can be opened through various video applications, such as QuickTime or VLC.

You can also stream video via most supported browsers and other web-based applications by opening an HTML file that includes the same URL above. Below are HTML examples for different browser types.

HTML example for Chrome, Firefox, and Edge

HTML example for Safari

Custom Exports

 

List Files

Returns a list of files available for download.

GET https://<subscription>.api.retailnext.net/v1/downloads/list

prefix

string

A directory to search the files in.

Available prefixes are: custom_exports

Example Request

Example Response

Download File

Downloads a file available in the associated destination.

GET https://<subscription>.api.retailnext.net/v1/downloads/download

file*

string

The path to the file requested for download.

* required parameter

Example Request

Example Response