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 API Tokens. Visit System API Tokens to learn more.
Code Block |
---|
|
--basic --user <AccessKey>:<SecretKey> |
Table of Contents |
---|
minLevel | 3 |
---|
maxLevel | 3 |
---|
include | (Version 1 API|Version 2 API).* |
---|
indent | 30px |
---|
type | flat |
---|
separator | pipe |
---|
|
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
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "X-Page-Length: 20" \
"https://<subscription>.api.retailnext.net/v1/location" |
|
Example Response
Expand |
---|
|
Code Block |
---|
| 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:
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.
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "X-Page-Length: 20" -H "X-Page-Start: 20" \
"https://<subscription>.api.retailnext.net/v1/location" |
|
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
Table of Contents |
---|
minLevel | 3 |
---|
maxLevel | 3 |
---|
include | (Query Locations|Create Locations|Update Locations).* |
---|
type | flat |
---|
separator | pipe |
---|
|
Query Locations
Returns locations and related fields.
https://<subscription>.api.retailnext.net/v2/location
Example Request
Expand |
---|
|
This example filters for only store type locations and includes extra fields for store_id and occupancy_limit Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/location" |
Where the request.json file contains: Code Block |
---|
{
"extra_fields": [
"store.store_id",
"store.occupancy_limit"
],
"where": {
"and": [
{
"location_types": [
"store"
]
}
]
}
} |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"nodes": [
[
{
"store_id": "50",
"occupancy_limit": 50,
"location_type": "store",
"area": null,
"uuid": "aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9",
"parent_uuid": "22940210-f49b-11e6-944b-c0001cd87189",
"name": "Caspar City Plaza",
"type": "location",
"archive_date": null
},
{
"store_id": "101",
"occupancy_limit": 15,
"location_type": "store",
"area": null,
"uuid": "86b03ba2-a117-11ea-802c-c00010892d7a",
"parent_uuid": "01b1ed64-f49b-11e6-9ef8-400075388ff3",
"name": "Willow Glen",
"type": "location",
"archive_date": null
},
...
} |
|
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
Specify location_type
filters in your query to limit responses by certain location types. This is particularly useful when normal responses exceed the API pagination limit. The supported filters are:
display
entrance
fitting_room
other
store
region
Create Locations
Creates sublocations and regions.
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
Info |
---|
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
Expand |
---|
|
This example creates a new Display sublocation type within a store. Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/location/create" |
Where the request.json file contains: Code Block |
---|
{
"name": "Front Table",
"parent_uuid": "2512a786-a117-11ea-874c-8000df845ed7",
"location_type": "display",
"area": 53.1,
"aggregate_to_parent": true,
"aggregate_to_store": false
} |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"location_type": "display",
"aggregate_to_parent": true,
"aggregate_to_store": false,
"area": 53.1,
"uuid": "fb2d8bf5-c19e-11e8-b05c-40008b55ebf7",
"parent_uuid": "2512a786-a117-11ea-874c-8000df845ed7",
"name": "Front Table",
"type": "location",
"archive_date": null
} |
|
Update Locations
Update location fields.
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)
|
Example Request
Expand |
---|
|
This example updates a store by changing its name, area and occupancy limit; as well as moving it to a new parent region. Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-XPUT "https://<subscription>.api.retailnext.net/v2/location/<location_uuid>" |
Where the request.json file contains: Code Block |
---|
| {
"name": "Willow Glen Updated",
"parent_uuid": "286b1000-f8b1-11e7-9337-c0009584d333",
"area": 270.8,
"occupancy_limit": 20
} |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"occupancy_limit": 20,
"location_type": "store",
"area": 270.8,
"uuid": "<location_uuid>",
"parent_uuid": "286b1000-f8b1-11e7-9337-c0009584d333",
"name": "Willow Glen Updated",
"type": "location",
"archive_date": null
} |
|
Updating Locations in Bulk
You can update a bulk selection of locations to a specified parameter value in certain situations.
Expand |
---|
title | Show bulk update occupancy limit example |
---|
|
This example updates the respective occupancy limit parameter of multiple store locations. Code Block |
---|
| while IFS=, read -r site_uuid occupancy;do curl -viL --basic --user <AccessKey>:<SecreteKey> \
-XPUT "https://<subscription>.api.retailnext.net/v2/location/$site_uuid" \
-d "{\"occupancy_limit\": $occupancy}";done < ./occupancy_limit.csv |
Where the occupancy_limit.csv file contains: Code Block |
---|
site_uuid, occupancy_limit
18ef3a2e-cc3f-11e6-8d5c-0000124e6871,40
ff94800e-7c5f-11e6-8056-c000704d0145,35 |
|
Store Hours
Query Store Hours
Returns store hours within specified parameters.
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
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/storehours" |
Where the request.json file contains: Code Block |
---|
| {
"stores" : [
"aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9", "aec5c886-9e2c-11e5-9bb7-0e5ba9bee1b9"
],
"start_date" :
"2021-01-15T00:00:00Z"
,
"end_date" :
"2021-01-22T00:00:00Z"
} |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"result": {
"aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9": {
"2021-01-15T00:00:00Z": {
"store_uuid": "aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9",
"effective_day": "2021-01-15T00:00:00Z",
"open": "2021-01-15T10:00:00Z",
"close": "2021-01-15T21:00:00Z"
},
...
},
"2021-01-22T00:00:00Z": {
"store_uuid": "aec5c886-9e2c-11e5-9bb7-0e5ba9bee1b9",
"effective_day": "2021-01-22T00:00:00Z",
"open": "2021-01-22T09:00:00Z",
"close": "2021-01-22T21:00:00Z"
}
}
}
} |
|
Datamine
Query Metrics
Returns metrics within specified parameters.
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
Info |
---|
Datamine API responses typically include the following indicators: Ok: When querying any metric, each response entry includes an ok field. A value of true means that there was no error in serving the data, while false indicates there was an error with a further description. Errors in serving data generally relate to inadequate API token permissions or bad requests, e.g. if you’re querying metrics for a store that is not included in the Location Profile assigned to your API token. Validity: When querying traffic metrics, each data point additionally includes a validity field. The possible values are: complete , incomplete and imputed , where an incomplete or imputed response means that there was a problem collecting traffic data during the queried range, e.g. power not supplied to the sensor. Learn more about traffic validation and imputing at /wiki/spaces/KB/pages/143785991.
Response timestamps are prefixed with - or + when the store hours of a store on a given day are configured to overlap with the previous day or the following day, respectively. See Managing Store Hours for more information.
|
Example Request
Expand |
---|
|
This example queries Traffic In & Out metrics for last week during store hours, with the response grouped by one day. Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine" |
Where the request.json file contains: Code Block |
---|
| {
"metrics" : [
"traffic_in",
"traffic_out"
],
"date_ranges" : [
{
"from": {
"relative": {
"add_weeks": -1 }
},
"to": {
"relative": {
"base": {
"name": "now" },
"truncate_to": "week"
}
}
}
],
"time_ranges" : [
{
"type": "store_hours"
}
],
"group_bys" : [
{
"group": "date",
"unit": "days",
"value": 1
}
],
"locations" : [
"aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9"
],
"time_zone": "America/Los_Angeles"
} |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"ok": true,
"metrics": [
{
"name": "traffic_in",
"ok": true,
"data": [
{
"value": 173,
"validity": "complete",
"group": {
"type": "date",
"from": {
"gregorian": "2021-02-21",
"year": 2021,
"month": 1,
"day": 22
},
"through": {
"gregorian": "2021-02-21",
"year": 2021,
"month": 1,
"day": 22
}
},
"index": 0
},
...
]
},
{
"name": "traffic_out",
"ok": true,
"data": [
{
"value": 174,
"validity": "complete",
"group": {
"type": "date",
"from": {
"gregorian": "2021-02-21",
"year": 2021,
"month": 1,
"day": 22
},
"through": {
"gregorian": "2021-02-21",
"year": 2021,
"month": 1,
"day": 22
}
},
"index": 0
},
...
]
}
]
} |
|
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
.
Info |
---|
Date range considerations: The date_ranges parameter and datamine API responses respect the subscription’s Admin Settings > Calendar configuration. For example: if your query specifies an absolute date range from year:2021, week:5, day:1, and your calendar has been customized such that Saturday is the first day of the week, the response will return metrics starting from Saturday, 30 January 2021. The maximum date range for queries, i.e. the difference in time between from and to , are as follows: If only one store location is queried, the limit is 5 years If several stores are queried, the limit is 2 years
|
Expand |
---|
title | Show date_ranges options |
---|
|
NameThe name key supports simple named date values, such as now and today . Info |
---|
Specifying a time zone in your query is required when using name within the date range parameter. Jump to Time Zones in the Occupancy section to learn more. |
Example Request Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine" |
Where the request.json file contains: Code Block |
---|
| {
...
"date_ranges" : [
{
"from": {
"name": "today" },
"to": {
"name": "now" }
}
],
...
"time_zone": "America/Los_Angeles"
} |
GregorianThe 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 Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine" |
Where the request.json file contains: Code Block |
---|
| {
...
"date_ranges" : [
{
"from": {
"gregorian": "2021-02-27T00:00:00Z" },
"to": {
"gregorian": "2021-02-28T00:00:00Z" }
}
],
...
} |
AbsoluteThe absolute key supports various date pairs with integer values. Example Request Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine" |
Where the request.json file contains: Code Block |
---|
| {
...
"date_ranges" : [
{
"from": {
"absolute": {
"year": 2021,
"week": 2,
"day": 4 }
},
"to": {
"absolute": {
"year": 2021,
"week": 3 }
}
}
],
...
} |
Supported Options Code Block |
---|
{
"absolute": {
"year": 2017, // calendar year, required
"quarter": 1, // calendar quarter, starts from 1, optional
"month": 1, // calendar month, starts from 1, optional
"week": 1, // calendar week, starts from 1, optional
"day": 1, // calendar day, starts from 1, optional
"hour": 0, // hour, starts from 0, optional
"minute": 0, // minute, starts from 0, optional
"second": 0 // second, starts from 0, optional
}
} |
Date Examples Code Block |
---|
// beginning of first day of 2017
year=2017
// beginning of 150th day of 2017
year=2017,day=150
// beginning of 12th week of 2017
year=2017,week=12
// beginning of 2018
year=2017,month=13
// 45th min of 12th hour of 5th day of 2nd week of 3rd month of 2nd quarter of 2017
year=2017,quarter=2,month=3,week=2,day=5,hour=12,minute=45 |
RelativeThe 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 Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine" |
Where the request.json file contains: Code Block |
---|
| {
...
"date_ranges" : [
{
"from": {
"relative": {
"base": {
"gregorian": "2021-02-27T00:00:00Z" }
}
},
"to": {
"relative": {
"add_days": 5 }
}
}
],
...
} |
Supported Options Code Block |
---|
{
"relative": {
"base": <date>, // any date option, required if "from" and "to" are both "relative"
"truncate_to": <interval>, // truncate base to specified interval (year|quarter|month|week|day|hour|minute|second), optional
"add_years": 1, // add specified number of years, optional
"add_quarters": 1, // add specified number of quarters, optional
"add_months": 1, // add specified number of months, optional
"add_weeks": 1, // add specified number of weeks, optional
"add_days": 1, // add specified number of days, optional
"add_hours": 1, // add specified number of hours, optional
"add_minutes": 1, // add specified number of minutes, optional
"add_seconds": 1, // add specified number of seconds, optional
}
} |
Info |
---|
Negative values are supported in order to specify a backward-looking interval. When adding months, the API maintains the same day-of-month as the starting date. If the destination month has too few days, it truncates the day of month to the final day. For example, with the Gregorian calendar, adding 1 month to "Jan 31" yields "Feb 28" (or "Feb 29" in leap year). Adding quarters is equivalent to adding 3 months, and adding years is equivalent to adding 12 months.
|
Mixed OptionsYou 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 Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine" |
Date range for June, 2020 plus 4 months - the request.json file contains: Code Block |
---|
| {
...
"date_ranges" : [
{
"from": {
"absolute": {
"year": 2020,
"month": 6 }
},
"to": {
"relative": {
"add_months": 4 }
}
}
],
...
} |
Date range for last week - the request.json file contains: Code Block |
---|
| {
...
"date_ranges" : [
{
"from": {
"relative": {
"add_weeks": -1 }
},
"to": {
"relative": {
"base": {
"name": "now" },
"truncate_to": "week"
}
}
}
],
...
"time_zone": "America/Los_Angeles"
} |
Date range for current month-to-date - the request.json file contains: Code Block |
---|
| {
...
"date_ranges" : [
{
"from": {
"relative": {
"base": {
"name": "now" },
"truncate_to": "month"
}
},
"to": {
"name": "now" }
}
],
...
"time_zone": "America/Los_Angeles"
} |
Date range for the last 24 hours - the request.json file contains: Code Block |
---|
{
...
"date_ranges": [
{
"from": {
"relative": {
"add_days": -1
}
},
"to": {
"relative": {
"base": {
"name": "now"
},
"truncate_to": "minute"
}
}
}
],
"time_ranges": [
{
"from": "00:00", "until": "24:00"
}
],
"group_bys": [
{
"group": "location",
"unit": "",
"value": 1
},
{
"group": "date",
"unit": "days",
"value": 1
},
{
"group": "time",
"unit": "hours",
"value": 1
}
],
...
"time_zone": "America/Los_Angeles"
} |
|
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.
Expand |
---|
title | Show group_bys options |
---|
|
Example Requests Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine" |
Single Grouping by date - the request.json file contains: Code Block |
---|
| {
...
"group_bys" : [
{
"group": "date",
"unit": "days",
"value": 1
}
],
...
} |
Layered Grouping by location, then time - the request.json file contains: Code Block |
---|
| {
...
"group_bys" : [
{
"group": "location",
"unit": "",
"value": 1
},
{
"group": "time",
"unit": "hours",
"value": 1
}
],
...
} |
Supported Options Code Block |
---|
| "group_bys": [
{
"group": "location",
"unit": "", // blank value required when grouping by "location"
"value": 1 // irrelevant, but accepts any positive integer
},
{
"group": "date",
"unit": "<string>", // supports "days", "weeks", "months" and "years"
"value": <integer> // any positive integer
},
{
"group": "time",
"unit": "<string>", // supports "hours" and "minutes"
"value": <integer> // any positive integer
},
{
"group": "day_of_week",
"unit": "", // blank value required when grouping by "day_of_week"
"value": 1 // irrelevant, but accepts any positive integer
}
] |
|
Occupancy
Table of Contents |
---|
minLevel | 3 |
---|
maxLevel | 3 |
---|
include | (Query Occupancy|Update Occupancy).* |
---|
type | flat |
---|
separator | pipe |
---|
|
Query Occupancy
Returns current occupancy metrics.
https://<subscription>.api.retailnext.net/v2/datamine
Example Request
Expand |
---|
|
This example queries for the current occupancy of the store location dace69f6-b307-11e9-819d-0000698cf233 . Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine" |
Where the request.json file contains: Code Block |
---|
| {
"date_ranges" : [
{
"from" : { "name":"today" },
"to" : { "relative" : {"add_days" : 1}}
}
],
"group_bys" : [
{
"group" : "location",
"unit" : "",
"value" : 0
}
],
"locations" : [
"dace69f6-b307-11e9-819d-0000698cf233"
],
"metrics" : [
"traffic_in",
"traffic_out",
"total_occupancy"
],
"time_ranges" : [
{"type": "store_hours"}
],
"time_zone": "America/Los_Angeles"
} |
Info |
---|
When using date range specifications "to" : { "name":"now" } , the system automatically truncates data up to the last complete 15 minute bucket in the day to allow fair comparisons against past period. To bypass this and retrieve metrics beyond the last complete 15 minute bucket, specify "to" : { "relative" : {"add_days" : 1}} instead to retrieve the most up to date count possible. |
|
Example Response
Expand |
---|
|
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. Code Block |
---|
| {
"metrics" : [
{
"data" : [
{
"group" : {
"name" : "San Jose Store",
"qualified_name" : "San Jose Store",
"type" : "location",
"uuid" : "dace69f6-b307-11e9-819d-0000698cf233"
},
"index" : 0,
"validity" : "complete",
"value" : 5
}
],
"name" : "traffic_in",
"ok" : true
},
{
"data" : [
{
"group" : {
"name" : "San Jose Store",
"qualified_name" : "San Jose Store",
"type" : "location",
"uuid" : "dace69f6-b307-11e9-819d-0000698cf233"
},
"index" : 0,
"validity" : "complete",
"value" : 4
}
],
"name" : "traffic_out",
"ok" : true
},
{
"data" : [
{
"group" : {
"name" : "San Jose Store",
"qualified_name" : "San Jose Store",
"type" : "location",
"uuid" : "dace69f6-b307-11e9-819d-0000698cf233"
},
"index" : 0,
"validity" : "complete",
"value" : 1
}
],
"name" : "total_occupancy",
"ok" : true
}
],
"ok" : true
} |
|
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.
Expand |
---|
title | Show time zone examples |
---|
|
With Time ZoneObtain the time zone of a location using /v2/location . Example RequestIn the example request below, dace69f6-b307-11e9-819d-0000698cf233 is the store location. Code Block |
---|
{
"extra_fields" : [
"store.time_zone"
],
"where" : {
"uuids" : [
"dace69f6-b307-11e9-819d-0000698cf233"
]
}
}
|
Example Response Code Block |
---|
{
"nodes" : [
[
{
"archive_date" : null,
"area" : null,
"location_type" : "store",
"name" : "San Jose Store",
"parent_uuid" : "df62161a-64c8-11e6-82d4-c0008ffc38ce",
"time_zone" : "America/Los_Angeles",
"type" : "location",
"uuid" : "dace69f6-b307-11e9-819d-0000698cf233"
}
]
]
}
|
Without TimezoneAlternatively, you can eliminate the need to supply timezone specifications by using a special time zone string local instead to return occupancy data as of the current moment in time. Such queries must conform to the following restrictions: Only total_occupancy and occupancy_limit metrics are requested Group by location Supply a single date range with from today to now Supply a single time range of store_hours
Example RequestRequest current occupancy for store location dace69f6-b307-11e9-819d-0000698cf233 using /v2/datamine . Code Block |
---|
{
"date_ranges" : [
{
"from" : { "name":"today" },
"to" : { "name":"now" }
}
],
"group_bys" : [
{
"group" : "location",
"unit" : "",
"value" : 0
}
],
"locations" : [
"dace69f6-b307-11e9-819d-0000698cf233"
],
"metrics" : [
"total_occupancy",
"occupancy_limit"
],
"time_ranges" : [
{"type": "store_hours"}
],
"time_zone": "local"
} |
Example Response Code Block |
---|
| {
"metrics" : [
{
"data" : [
{
"group" : {
"name" : "San Jose Store",
"qualified_name" : "San Jose Store",
"type" : "location",
"uuid" : "dace69f6-b307-11e9-819d-0000698cf233"
},
"index" : 0,
"validity" : "complete",
"value" : 179
}
],
"name" : "total_occupancy",
"ok" : true
},
{
"data" : [
{
"group" : {
"name" : "San Jose Store",
"qualified_name" : "San Jose Store",
"type" : "location",
"uuid" : "dace69f6-b307-11e9-819d-0000698cf233"
},
"index" : 0,
"validity" : "complete",
"value" : 300
}
],
"name" : "occupancy_limit",
"ok" : true
}
],
"ok" : true
} |
|
Update Occupancy
Update occupancy by a specified adjustment value.
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
Info |
---|
Occupancy updates are only accepted within store hours and when the store’s occupancy limit is defined. |
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/occupancy/adjust" |
Where the request.json file contains: Code Block |
---|
| {
"store_uuid" : "813737be-9f9d-11ea-8372-000008adea78",
"adjustment_time" : "2021-03-16T12:00:00+00:00",
"adjustment_count" : 5
} |
|
Users
Table of Contents |
---|
minLevel | 3 |
---|
maxLevel | 3 |
---|
include | (Query Users|Create Users|Update Users).* |
---|
type | flat |
---|
separator | pipe |
---|
|
Query Users
Returns users and related fields.
https://<subscription>.api.retailnext.net/v1/users
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/users" |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"users": [
{
"type": "local",
"name": "RetailNext_User",
"email": "retailnextuser@domain.com",
"id": "2abe8330-5e0f-11ea-8522-c0009d2f3ea6",
"disabled": false,
"user_profile_id": "f76545a0-5e0e-11ea-8d71-c0003468dbae",
"location_profile_id": "fb1fcd84-7b9c-11e7-937e-4000eba63dc2",
"last_sign_in_at": "2020-03-04T12:00:28.742Z",
"current_sign_in_at": "2020-03-04T12:01:06.2Z",
"invitation_accepted": true,
"invitation_locale": "en_US"
},
...
]
} |
|
Filtering
By appending the URL, you can filter your response to only include users with a specified parameter’s value.
Expand |
---|
title | Show filtering examples |
---|
|
TypeIf 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. Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/users?type=SSO" |
EmailThe example below queries for users with an email address that exactly matches storemanager@domain.com Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/users?email=storemanager0@domain.com |
|
Create Users
Creates an SSO user account.
https://<subscription>.api.retailnext.net/v1/users
Parameters
email*email address | User email address |
type*string | Type of user account. Only sso value accepted. |
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 location_profile_id , see Custom Locations for details. |
* required parameter
** conditionally required parameter
Info |
---|
If Use SAML Attribute is selected in Admin Settings > Single Sign-on: you cannot specify the user’s permissions in RetailNext (i.e. user and/or location profile) as these are managed through the organization's Identity Provider If, instead, Manage on Users page is selected in Admin Settings > Single Sign-on: you must specify the user’s permissions (i.e. user and/or location profile) when creating a new user You can only create users if you have the permission: Manage users and location profiles. Similarly, you can only create or view users in RetailNext with the same or lower user and/or location profile permissions compared to yours.
|
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-XPOST "https://<subscription>.api.retailnext.net/v1/users" |
Where the request.json file contains: Code Block |
---|
| {
"user": {
"email":
"sandra.bloch@domain.com",
"type":
"sso",
"name":
"Sandra Bloch",
"disabled":
false,
"user_profile_id":
"8b26a6c0-5027-11eb-8039-8000f92819c5",
"location_profile_id":
"9e701012-4c76-11e7-853d-c0001c66456e"
}
} |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"user": {
"type": "sso",
"name": "Sandra Bloch",
"email": "sandra.bloch@domain.com",
"id": "dc2e3c2e-5029-11eb-8b74-40002f864577",
"disabled": false,
"user_profile_id": "8b26a6c0-5027-11eb-8039-8000f92819c5",
"location_profile_id": "9e701012-4c76-11e7-853d-c0001c66456e",
}
} |
|
Update Users
Update the permissions of a user.
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. |
Info |
---|
Updating the user or location profile of another user requires that the requestor's user account has the same or higher permissions. |
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-XPUT "https://<subscription>.api.retailnext.net/v1/users/<user_uuid>" |
Where the request.json file contains: Code Block |
---|
| {
"user_profile_id" :
"74178848-bbf4-11e8-8fcb-40000e637ca2",
"location_profile_id" :
"93334489-6d6a-11eb-9ec3-00000d9c1e4f"
} |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"user": {
"type": "local",
"name": "RN user",
"email": "rnuser@domain.com",
"id": "332e3c2e-5029-11eb-8b74-40002f864572",
"disabled": false,
"user_profile_id": "74178848-bbf4-11e8-8fcb-40000e637ca2",
"location_profile_id": "93334489-6d6a-11eb-9ec3-00000d9c1e4f",
"last_sign_in_at": "2021-01-06T14:16:53.597Z",
"current_sign_in_at": "2021-01-11T10:21:25.407Z",
"invitation_accepted": true,
"invitation_locale": "en_US"
}
} |
|
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.
Expand |
---|
title | Show custom locations example |
---|
|
Example Request Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-XPUT "https://<subscription>.api.retailnext.net/v1/users/<user_uuid>" |
Where the request.json file contains: Code Block |
---|
| {
"location_ids": [
"3749e26c-a7da-11e8-9eae-40007c493637",
"64b13bf4-35af-11e7-9c1c-c000609b0f52"
]
} |
Example Response Code Block |
---|
| {
"user": {
"type": "local",
"name": "RN user",
"email": "rnuser@domain.com",
"id": "332e3c2e-5029-11eb-8b74-40002f864572",
"disabled": false,
"user_profile_id": "64178848-bbf4-11e8-8fcb-40000e637ca1",
"location_ids": [
"3749e26c-a7da-11e8-9eae-40007c493637",
"64b13bf4-35af-11e7-9c1c-c000609b0f52"
],
"last_sign_in_at": "2021-01-06T14:16:53.597Z",
"current_sign_in_at": "2021-01-11T10:21:25.407Z",
"invitation_accepted": true,
"invitation_locale": "en_US"
}
} |
|
User Profiles
Query User Profiles
Returns user profiles and related fields.
https://<subscription>.api.retailnext.net/v1/user_profiles
Info |
---|
To query a specific user profile, append the above URL with /<user_profile_uuid> |
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/user_profiles" |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"user_profiles": [
{
"id": "b43dfbe6-1b4d-11e9-93fd-4000551d9e45",
"name": "API Example",
"enterprise_groups": [],
"use_idle_timeout": false,
"idle_timeout": 54000,
"subscription_admin": false,
"visible_dashboard_widgets": {
"pages": [
"analytics",
"reports",
"point_of_sale"
],
"data_types": [
"export_analytics_data",
"guest_wifi",
"individual_data",
"mobile_device_detection",
"pos",
"pos_exception_data",
"pos_individual_transactions",
"pos_transactions_export",
"access_reports",
"staffing_data",
"tracks_and_kinetic_maps",
"traffic"
],
"admin_tasks": [
"health_monitoring_alerts",
"cameras",
"pos_terminals",
"security_event_sources",
"store_appliances",
"fpa",
"pos_uploads",
"sku_map_uploads",
"staff_hour_uploads",
"traffic_uploads",
"store_hours_uploads",
"goals_uploads",
"currency_uploads",
"deleted_items",
"dwell_uploads"
],
"allow_individual_activity": [
"mobile_device_detection"
]
}
},
...
]
} |
|
Location Profiles
Query Location Profiles
Returns location profiles and related fields.
https://<subscription>.api.retailnext.net/v1/location_profiles
Info |
---|
To query a specific location profile, append the above URL with /<location_profile_uuid> |
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/location_profiles" |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"location_profiles": [
{
"id": "bffb9ff6-1b4d-11e9-8b97-000006c38736",
"name": "API Example",
"enterprise_groups": [],
"location_ids": [
"e235aee4-cf7a-11e5-973e-8000a847d47a"
]
},
...
]
} |
|
Health Monitoring
Query Health Alerts
Returns health alerts and related fields.
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
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/healthalerts" |
Where the request.json file contains: Code Block |
---|
| {
"start_time" : "2021-01-22T00:00:00Z"
} |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"result": [
{
"alert_creation_time": "2021-01-11T11:38:34.942-08:00",
"description": "Haven't heard from Aurora sensor recently",
"event_time": "2021-01-11T10:38:34-08:00",
"resolved": true,
"resolved_time": "2021-01-12T14:11:33.522-08:00",
"severity": "resolved",
"store_uuid": "aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9",
"store_name": "Caspar City Plaza",
"subject_id": "20:C3:A4:80:09:69",
"subject_name": "CCP Aurora (20:C3:A4:80:09:69)",
"type": "connectiondown",
"uuid": "97fd95e0-5444-11eb-8b83-40003ca6d233",
"obsolete": false
},
...
]
} |
|
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.
Predicted Traffic
Query Predicted Traffic
Returns predicted traffic metrics within specified parameters.
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
Info |
---|
Responses are grouped into 15-minute intervals. This cannot be configured. In one query, up to 7 days can be requested. For additional days, use multiple requests. Predicted traffic is available for the upcoming month, up to 31 days. Queries exceeding this range will return an error. Sufficient historical data is required for predictions See /wiki/spaces/KB/pages/3005349996 to learn more about the traffic prediction model Predicted Traffic API supports 3 concurrent requests per subscription. Requests exceeding this limit will receive error HTTP 429.
|
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/predictedtraffic" |
Where the request.json file contains: Code Block |
---|
| {
"store_uuid" : "aec5c886-9e2c-11e5-9bb7-0e5ba9bee1b9",
"first_day" : "2021-03-17",
"last_day" : "2021-03-23"
} |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"ok": true,
"error": "",
"predictions": [
{
"time": "2021-03-17T09:00:00Z",
"value": 10
},
{
"time": "2021-03-17T09:15:00Z",
"value": 10
},
...
{
"time": "2021-03-23T20:45:00Z",
"value": 3
}
]
} |
|
Zone Transitions
Query Zone Transitions
Returns FPA zone transition metrics within specified parameters.
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
Expand |
---|
|
This example queries Traffic In & Out metrics for last week during store hours, with the response grouped by one day. Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/zone_transitions" |
Where the request.json file contains: Code Block |
---|
| {
"locations" : [
"cdf7322e-3329-11ea-8e45-80003c755d3e",
"f1cc33f2-3329-11ea-9b32-80001a18e60d"
],
"date_ranges" : [
{
"start": "2021-02-15",
"finish": "2021-02-22"
}
],
"metrics" : [
"customer"
],
"transitions" :
"direct_and_indirect",
"dwells" :
"all_traffic",
"time_ranges" : [
{
"start": "10:30",
"finish": "13:00"
}
],
"days_of_week" : [
"friday",
"saturday"
]
} |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"metrics": [
{
"name": "customer",
"data": [
{
"floorplan": {
"uuid": "e0acd09e-2e7a-11ea-8b1a-40002569de69",
"name": "Garden Station Floorplan",
"store_uuid": "af1fd977-9e2c-11e5-9bbe-0e5ba9bee1b9",
"store_name": "Garden Station"
},
"zones": [
{
"uuid": "a1ec24c6-2e7b-11ea-960c-8000bec20274",
"name": "Entrance",
"location_uuid": "f1cc33f2-3329-11ea-9b32-80001a18e60d",
"location_name": "Entrance Zone"
},
{
"uuid": "a34979f4-2e7b-11ea-8dfd-c000826898db",
"name": "Denim",
"location_uuid": "cdf7322e-3329-11ea-8e45-80003c755d3e",
"location_name": "Denim Zone"
}
],
"transitions": [
{
"from_zone_id": "a1ec24c6-2e7b-11ea-960c-8000bec20274",
"to_zone_id": "a1ec24c6-2e7b-11ea-960c-8000bec20274",
"value": 170,
"percentage": 54
},
{
"from_zone_id": "a1ec24c6-2e7b-11ea-960c-8000bec20274",
"to_zone_id": "a34979f4-2e7b-11ea-8dfd-c000826898db",
"value": 147,
"percentage": 46
},
{
"from_zone_id": "a34979f4-2e7b-11ea-8dfd-c000826898db",
"to_zone_id": "a1ec24c6-2e7b-11ea-960c-8000bec20274",
"value": 42,
"percentage": 69
},
{
"from_zone_id": "a34979f4-2e7b-11ea-8dfd-c000826898db",
"to_zone_id": "a34979f4-2e7b-11ea-8dfd-c000826898db",
"value": 19,
"percentage": 31
}
]
}
]
}
]
} |
|
FPA Zones
Query FPA Zones
Returns FPA floorplans and related fields.
https://<subscription>.api.retailnext.net/v1/fpafloorplans
Info |
---|
The example queries all FPA floorplans within a subscription. To query all floorplans within a specific store, use https://<subscription>.api.retailnext.net/v1/stores/<store_uuid>/fpafloorplans To query a specific floorplan, use https://<subscription>.api.retailnext.net/v1/fpafloorplans/<floorplan_uuid>
|
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/fpafloorplans" |
|
Example Response
Expand |
---|
|
Code Block |
---|
| [
{
"id": "7ce0f10c-508f-11eb-9c50-000048e74782",
"name": "API Store Floorplan",
"store_id": "aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9",
"store_name": "API Store",
"zones": [
{
"id": "f64b51ac-546f-11eb-9441-8000514932de",
"name": "Table 1",
"type": "fpa",
"location_id": "24f99a38-5478-11eb-98ec-40002ded88bc",
"location_name": "FPA Zones",
"area": 46907.55844251474,
"dwell_time_threshold_ms": 10,
"zone_threshold_mm": 1000,
"points": [
{
"x": 1751.2620277487956,
"y": 384.9399262748038
},
{
"x": 1918.1988757176557,
"y": 383.3687429022536
},
{
"x": 1915.0491238691866,
"y": 664.610566588743
},
{
"x": 1746.5373999760916,
"y": 663.0393832161927
},
{
"x": 1751.2620277487956,
"y": 384.9399262748038
}
]
},
...
]
}
] |
|
Response Fields
Expand |
---|
title | Show response field descriptions |
---|
|
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
Table of Contents |
---|
minLevel | 3 |
---|
maxLevel | 3 |
---|
include | (Query Cameras|Query Channels|Query Appliances).* |
---|
type | flat |
---|
separator | pipe |
---|
|
Info |
---|
Pagination - Inventory API queries use unique X-Page string values, rather than an integer as described for other v1 API methods. |
Query Cameras
Returns camera hardware and related fields.
https://<subscription>.api.retailnext.net/v1/inventory/cameras
Info |
---|
To query cameras in a specific store, use store_uuid parameter with store location unique id, by appending the above URL with ?store_uuid=<store_location_uuid> |
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/inventory/cameras" |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"ok": true,
"next_page": "CAC:13:37:D0:86:77",
"cameras": [
{
"type": 1,
"device_id": "20:C3:13:0F:1D:2A",
"device_name": "Aisle Camera",
"store_uuid": "a434a682-30a0-11ea-896a-00005f259c6e",
"appliance_id": "",
"vendor": "RetailNext",
"model": "Aurora",
"private_ip": "10.10.10.179",
"public_ip": "162.254.19.20",
"last_heard": "2020-01-14T22:30:18.363Z",
"serial_number": "",
"network_configuration": {
"mode": 0,
"ip": "",
"gateway": "",
"dns": "",
"ntp": ""
},
"video_channel_uuids": [
"d86d75e2-3338-11ea-95e3-000071946766"
],
"video_channel_count": 1,
"configuration_summary": {},
"analytics": {
"traffic_line_count": 1,
"dwell_zone_count": 0,
"direction_line_configured": false
},
"height": 3860
},
...
]
} |
|
Response Fields
Expand |
---|
title | Show response field descriptions |
---|
|
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 |
|
Note |
---|
Cameras Inventory API supports 3 concurrent requests per subscription. Requests exceeding this limit will receive error HTTP 429. |
Query Channels
Returns video channels and related fields.
https://<subscription>.api.retailnext.net/v1/inventory/channels
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/inventory/channels" |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"ok": true,
"next_page": "end",
"channels": [
{
"channel_uuid": "9290bc70-3480-11ea-81c9-c000c7e8079e",
"name": "Registration Desk",
"device_id": "92710a06-3480-11ea-9877-40003d3dd9a9",
"resolution": "1280x960",
"frame_rate": 10,
"record_on_motion": true,
"minimum_retention_days": 0,
"maximun_retention_days": 0,
"blur_video": false,
"recording_enabled": true,
"snapshot_enabled": true,
"snapshot_interval_secs": 300,
"snapshot_resolution": "1400x1050"
},
...
]
} |
|
Response Fields
Expand |
---|
title | Show response field descriptions |
---|
|
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.
https://<subscription>.api.retailnext.net/v1/inventory/appliances
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/inventory/appliances" |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"ok": true,
"next_page": "end",
"store_appliances": [
{
"appliance_id": "323231f8-6afg-11eb-8684-4000fc072082",
"store_uuid": "af21ffd8-9e2c-11e5-9bc9-0e5ba9bee1b9",
"mac_address": "00:0D:29:60:FB:CB",
"private_ip": "192.168.95.92",
"network_configuration": {
"mode": 0,
"ip": "",
"gateway": "",
"dns": "",
"ntp": ""
},
"public_ip": "104.59.220.132"
},
...
]
} |
|
Response Fields
Expand |
---|
title | Show response field descriptions |
---|
|
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
Table of Contents |
---|
minLevel | 3 |
---|
maxLevel | 3 |
---|
include | (Start Export|Query Export Status and Download).* |
---|
type | flat |
---|
separator | pipe |
---|
|
Start Export
Starts a video export within specified parameters.
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
Info |
---|
Successful video export requests return a location header in the format of /v1/video/export/task/<export_id> that can be used to subsequently download the video clip or to query its export status, as described in the next section. |
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XPOST "https://<subscription>.api.retailnext.net/v1/video/export/start?\
start=2021-03-17T13:00:00Z&end=2021-03-17T13:05:08Z\
&channel=f2b81aa0-8c90-11eb-9d08-c00017306bd8\
&analytics_overlay=1&raw=0&info_overlay=1" |
|
Example Response
Expand |
---|
|
Code Block |
---|
| HTTP/2 201
content-type: application/json
location: /v1/video/export/task/3ba9d435-8c91-11eb-9c23-0000d53335d2
...
<
{"ok":true} |
|
Query Export Status and Download
Returns the current status of a video export and, if ready, the download link.
https://<subscription>.api.retailnext.net/v1/video/export/task/<export_id>
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/video/export/task/3ba9d435-8c91-11eb-9c23-0000d53335d2" |
|
Example Response
Expand |
---|
|
Code Block |
---|
| HTTP/2 201
content-type: application/json
location: /v1/video/export/task/3ba9d435-8c91-11eb-9c23-0000d53335d2
...
<
{"ok":true} |
|
Info |
---|
The export status is detailed in the HTTP response code as follows. 202 Accepted - export is in progress
302 Found - export is ready. Download the file by using the provided location header URL.
404 Expired - export has expired
424 Failed - export has failed. The response includes the reason for failure.
Exports can be deleted by using HTTP DELETE, for example
-XDELETE "https://<subscription>.api.retailnext.net/v1/video/export/task/<export_id>"
|
Video Stream
Table of Contents |
---|
minLevel | 3 |
---|
maxLevel | 3 |
---|
include | (Generate Token|Stream Video).* |
---|
type | flat |
---|
separator | pipe |
---|
|
Generate Token
Returns a token to stream a video channel over HLS.
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
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/hlsapitoken" |
Where the request.json file contains: Code Block |
---|
| {
"location_uuid" : "22940210-f49b-11e6-944b-c0001cd78189"
} |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"token": "9wTw-pk1VLsEGzmzaH9vOL-a6RU"
} |
|
Stream Video
Using a generated token value, create an HLS M3U8 playlist to stream a video channel in the URL format below.
Code Block |
---|
|
https://<subscription>.api.retailnext.net/v1/hls/<video_channel_uuid>.m3u8?token=<token_value> |
The URL can be opened through various video applications, such as QuickTime or VLC.
Point of Sale
Integrate point of sale data via API.
Table of Contents |
---|
minLevel | 3 |
---|
maxLevel | 3 |
---|
include | (Upload Transactions|Query Single Transaction Status|Query Multiple Transactions Status).* |
---|
type | flat |
---|
separator | pipe |
---|
|
Upload Transactions
https://<subscription>.api.retailnext.net/v1/pos/transaction
Parameters
See Point of Sale Upload for the full list of parameters.
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/pos/transaction" |
Where the request.json file contains: Code Block |
---|
| {
"transactions": [
{
"store_id": "505",
"receipt_number": "12737",
"workstation_id": "4",
"division_id": "AA01",
"receipt_date_time": "2022-06-14 15:14:44",
"line_items_total": 100,
"transaction_total": 110,
"operator_ids": [
"0000099"
],
"transaction_type": "Sale",
"transaction_status": "Finished",
"payments": [
"cash",
"discover",
"gift card"
],
"tax_amount": 10,
"sales_associate_ids": [
"0000099"
],
"currency_code": "USD",
"line_items": [
{
"price": 100.0,
"quantity": 2,
"sku": "SKU001",
"description": "Item1",
"discount_percentage": 20
}
]
}
]
} |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"transactions": [
"d507e3e0-09e3-11ed-9157-400026b643f7"
],
"received_timestamp": "2022-07-22T17:29:25Z"
} |
|
Query Single Transaction Status
https://<subscription>.api.retailnext.net/v1/pos/transaction/status/<transaction-uuid>
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/pos/transaction/status/4d7aa93f-023c-11ed-98f4-0000589072c4" |
|
Example Response
Expand |
---|
|
Code Block |
---|
| {
"uuid": "4d7aa93f-023c-11ed-98f4-0000589072c4",
"upload_time": "2022-07-12T23:42:33Z",
"status": "processed",
"receipt_number": "12737",
"store_id": "505",
"division_id": "AA01",
"workstation_id": "4",
"receipt_date_time": "2022-06-14 15:14:44"
} |
|
Query Multiple Transactions Status
Query the status of all transactions uploaded in the last 24 hours.
https://<subscription>.api.retailnext.net/v1/pos/transaction/status/
Example Request
Expand |
---|
|
Code Block |
---|
| curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/pos/transaction/status" |
|
Example Response
Expand |
---|
|
Code Block |
---|
| [
{
"uuid": "9261b588-091e-11ed-9cad-c000ed0ebacf",
"upload_time": "2022-07-21T17:57:22Z",
"status": "processed",
"receipt_number": "99803",
"store_id": "T179",
"division_id": "TH001",
"workstation_id": "4",
"receipt_date_time": "2022-07-19 10:23:16"
},
{
"uuid": "2dd0b361-092e-11ed-8be3-c00087b07a3e",
"upload_time": "2022-07-21T19:49:06Z",
"status": "processed",
"receipt_number": "99803",
"store_id": "T003",
"division_id": "TH001",
"workstation_id": "4",
"receipt_date_time": "2022-07-19 10:23:16"
},
{
"uuid": "44e74195-092e-11ed-8ff8-40005dced8eb",
"upload_time": "2022-07-21T19:49:44Z",
"status": "processed",
"receipt_number": "99001",
"store_id": "T003",
"division_id": "TH001",
"workstation_id": "4",
"receipt_date_time": "2022-07-19 10:23:16"
}
] |
|
Info |
---|
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
|