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: Supported region type: |
area integer | The area in square feet (only applicable to sublocations) |
aggregate_to_parent boolean default: true when "entrance", false otherwise |
|
aggregate_to_store boolean default: true when "entrance", false otherwise |
|
* 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: |
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 |
aggregate_to_parent boolean |
|
aggregate_to_store boolean |
|
Changing the
location_type
to or from “store” or “region” is not supported (in other words, you can only change thelocation_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 Point of Sale Upload 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
andend_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
* 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 |
See More Details on Date Ranges below |
time_ranges* string |
|
group_bys* string |
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.
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 |
namestring 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 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 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 https://retailnext.atlassian.net/wiki/spaces/KB/pages/1500839941/File+Uploads#API 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 |
|
metrics string default: all |
|
transitions string default: direct_only |
|
dwells string default: dwells_only |
|
time_ranges string default: store_hours |
|
days_of_week string default: all days of week |
|
* 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 |
---|---|---|
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 |
---|---|---|
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 | 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 |
---|---|---|
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 |
---|---|---|
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 | 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 When multiple channels are specified, you may also provide a 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 |
|
info_overlay boolean default: 0 |
|
raw boolean default: 0 |
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: |
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
On This Page