Content Comparison

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

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

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

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

v2/location has a limit of 10,000 location nodes per response, and does not support pagination.

If your query is for more than 10,000 nodes, the response header will contain the code 400 with the body {"error":"bad_request","error_detail":"too many result nodes (XXXXX), please refine your query"}.

If you expect a large response that may get trimmed by this limit, be more specific in your query (e.g. use additional filters) or consider using v1/location which supports pagination.

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/location"

{
   "extra_fields": [
      "store.store_id",
      "store.occupancy_limit"
   ],
   "where": {
      "and": [
         {
            "location_types": [
               "store"
            ]
         }
      ]
   }
}

{
    "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
            },
...
}

{
  "root_uuids": ["05e54488-02f5-11eb-88c2-000025b8381c"],
  "where": {
      "and": [
         {
            "location_types": [
               "store"
            ]
         }
      ]
   }
}

• 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

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/location/create"

{
  "name": "Front Table",
  "parent_uuid": "2512a786-a117-11ea-874c-8000df845ed7",
  "location_type": "display",
  "area": 53.1,
  "aggregate_to_parent": true,
  "aggregate_to_store": false
}

{
  "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
}

• 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).

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-XPUT "https://<subscription>.api.retailnext.net/v2/location/<location_uuid>"

{
  "name": "Willow Glen Updated",
  "parent_uuid": "286b1000-f8b1-11e7-9337-c0009584d333",
  "area": 270.8,
  "occupancy_limit": 20
}

{
    "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
}

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

site_uuid, occupancy_limit
18ef3a2e-cc3f-11e6-8d5c-0000124e6871,40
ff94800e-7c5f-11e6-8056-c000704d0145,35

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/pos/transaction"

{
    "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
                    "discount_amount": 20                   
                }
            ]
        }
    ]
}

{
    "transactions": [
        "d507e3e0-09e3-11ed-9157-400026b643f7"
    ],
    "received_timestamp": "2022-07-22T17:29:25Z"
}

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/pos/transaction/status/4d7aa93f-023c-11ed-98f4-0000589072c4"

{
    "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"
}

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/pos/transaction/status"

[
    {
        "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"
    }
]

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

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/storehours"

{
    "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"
}

{
    "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"
            }
        }
    }
}

• The open and close timestamps in store hours query responses are always presented in the store’s local timezone, as configured in Admin Settings > Locations for a particular store. Ignore the Z i.e. UTC timezone indicator in the response for this API method.

• 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.

• Responses will only include completed time intervals. For example, if a store’s local time is 09:53 at the time when a query is made for the interval 09:00 - 10:00 and grouped by 15-min, the response will be limited to the three completed time intervals: 09:00 - 09:15, 09:15 - 09:30, and 09:30 - 09:45.

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"

{
   "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"
}

{
    "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
                },
...
            ]
        }
    ]
}

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

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.

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"

{
...
    "date_ranges" : [
      {
      "from": {
         "name": "today" },
      "to": {
         "name": "now" }
      }
   ],
...
   "time_zone": "America/Los_Angeles"
}

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"

{
...
    "date_ranges" : [
      {
      "from": {
         "gregorian": "2021-02-27T00:00:00Z" },
      "to": {
         "gregorian": "2021-02-28T00:00:00Z" }
      }
    ],
...
}

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"

{
...
    "date_ranges" : [
      {
      "from": {
         "absolute": {
            "year": 2021,
            "week": 2,
            "day": 4 }
          },
      "to": {
         "absolute": {
            "year": 2021,
            "week": 3 }
          }
      }
    ],
...
}

{
"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
  }
}

// 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

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"

{
...
    "date_ranges" : [
      {
      "from": {
        "relative": {
          "base": {
            "gregorian": "2021-02-27T00:00:00Z" }
          }
        },
      "to": {
        "relative": {
          "add_days": 5 }
        }
      }
    ],
...
}

{
  "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
  }
}

• 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.

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"

{
...
    "date_ranges" : [
      {
      "from": {
        "absolute": {
          "year": 2020,
          "month": 6 }
        },
      "to": {
        "relative": {
          "add_months": 4 }
        }
      }
    ],
...
}

{
...
    "date_ranges" : [
      {
      "from": {
        "relative": {
          "add_weeks": -1 }
        },
      "to": {
        "relative": {
          "base": {
            "name": "now" },
        "truncate_to": "week"
          }
        }
      }
    ],
...
   "time_zone": "America/Los_Angeles"
}

{
...
    "date_ranges" : [
      {
      "from": {
        "relative": {
          "base": {
             "name": "now" },
         "truncate_to": "month"
          }
        },
      "to": {
        "name": "now" }
      }
    ],
...
  "time_zone": "America/Los_Angeles"
}

{
...
   "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"
}

• When grouping by location, name and qualified_name fields are included in API responses.

  • name is the configured location name

  • qualified_name is not configurable, and its purpose is to deduplicate a location or hierarchy object name when names are duplicated in the same subscription. If the name value is unique, the qualified_name value will repeat it.

  • Note: Store ID is not included in datamine responses. You can query locations to get the Store ID associated with a store name.

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"

{
...
    "group_bys" : [
      {
      "group": "date",
      "unit": "days",
      "value": 1
      }
    ],
...
}

{
...
    "group_bys" : [
      {
      "group": "location",
      "unit": "",
      "value": 1
      },
      {
      "group": "time",
      "unit": "hours",
      "value": 1
      }
    ],
...
}

"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
  }
]

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"

{
    "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"
}

{
   "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
}

{
   "extra_fields" : [
      "store.time_zone"
   ],
   "where" : {
      "uuids" : [
         "dace69f6-b307-11e9-819d-0000698cf233"
      ]
   }
}

{
   "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"
         }
      ]
   ]
}

Occupancy updates are only accepted within store hours and when the store’s occupancy limit is defined.

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/occupancy/adjust"

{
      "store_uuid" : "813737be-9f9d-11ea-8372-000008adea78",
      "adjustment_time" : "2021-03-16T12:00:00+00:00",
      "adjustment_count" : 5
}

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/users"

{
    "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"
        },
...
    ]
}

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/users?type=SSO"

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/users?email=storemanager0@domain.com

• 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.

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-XPOST "https://<subscription>.api.retailnext.net/v1/users"

{
   "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"
   }
}

{
    "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",
    }
}

Updating the user or location profile of another user requires that the requestor's user account has the same or higher permissions.

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-XPUT "https://<subscription>.api.retailnext.net/v1/users/<user_uuid>"

{
    "user_profile_id" :
       "74178848-bbf4-11e8-8fcb-40000e637ca2",
    "location_profile_id" :
       "93334489-6d6a-11eb-9ec3-00000d9c1e4f"
}

{
    "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"
    }
}

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-XPUT "https://<subscription>.api.retailnext.net/v1/users/<user_uuid>"

{
    "location_ids": [
        "3749e26c-a7da-11e8-9eae-40007c493637",
        "64b13bf4-35af-11e7-9c1c-c000609b0f52"
    ]
}

{
    "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"
    }
}

To query a specific user profile, append the above URL with /<user_profile_uuid>

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/user_profiles"

{
    "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"
                ]
            }
        },
...
    ]
}     

To query a specific location profile, append the above URL with /<location_profile_uuid>

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/location_profiles"

{
    "location_profiles": [
        {
            "id": "bffb9ff6-1b4d-11e9-8b97-000006c38736",
            "name": "API Example",
            "enterprise_groups": [],
            "location_ids": [
                "e235aee4-cf7a-11e5-973e-8000a847d47a"
            ]
        },
...
    ]
}

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/healthalerts"

{
      "start_time" : "2021-01-22T00:00:00Z"
}

{
    "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
        },
...
    ]
}

• 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.

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/predictedtraffic"

{
      "store_uuid" : "aec5c886-9e2c-11e5-9bb7-0e5ba9bee1b9",
      "first_day" : "2021-03-17",
      "last_day" : "2021-03-23"
}

{
    "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
        }
    ]
}

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/zone_transitions"

{
    "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"
   ]
}

{
    "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
                        }
                    ]
                }
            ]
        }
    ]
}

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>

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/fpafloorplans"

[
    {
        "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
                    }
                ]
            },
...
        ]
    }
]

Pagination - Inventory API queries use unique X-Page string values, rather than an integer as described for other v1 API methods.

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>

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/inventory/cameras"

{
    "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
        },
...
    ]
}

Cameras Inventory API supports 3 concurrent requests per subscription. Requests exceeding this limit will receive error HTTP 429.

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/inventory/channels"

{
    "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"
        },
...
    ]
}

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/inventory/appliances"

{
    "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"
        },
...
    ]
}

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.

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"

HTTP/2 201
content-type: application/json
location: /v1/video/export/task/3ba9d435-8c91-11eb-9c23-0000d53335d2
...
< 
{"ok":true}

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/video/export/task/3ba9d435-8c91-11eb-9c23-0000d53335d2"

HTTP/2 201
content-type: application/json
location: /v1/video/export/task/3ba9d435-8c91-11eb-9c23-0000d53335d2
...
< 
{"ok":true}

• 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>"

  • By default, exports are deleted after 7 days

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/hlsapitoken"

{
      "location_uuid" : "22940210-f49b-11e6-944b-c0001cd78189"
}

{
    "token": "9wTw-pk1VLsEGzmzaH9vOL-a6RU"
}

• See this example for step-by-step instructions to fetch parent location UUIDs (for token generation) and video channel UUIDs (for streaming) using location API queries

• Tokens expire after 24 hours

https://<subscription>.api.retailnext.net/v1/hls/<video_channel_uuid>.m3u8?token=<token_value>

<html lang="en">
    <head>
        <meta charset=utf-8/>
        <link href="https://unpkg.com/video.js/dist/video-js.css" rel="stylesheet">
      <script src="https://unpkg.com/video.js/dist/video.js"></script>
      <script src="https://unpkg.com/videojs-contrib-hls/dist/videojs-contrib-hls.js"></script>
    </head>
    <body>
        <div id='player'>
            <video id="my_video_1" class="video-js vjs-fluid vjs-default-skin" width="352" height="198" controls preload="auto"
            data-setup='{}'>
                    <source src="https://[subscription].retailnext.net/v1/hls/[video_channel_uuid].m3u8?token=[token_value]"
                    type="application/x-mpegURL">
                    </video>
        </div>
        <script>
            var player = videojs('my_video_1');
            player.play();
            </script>
    </body>
</html>

<html lang="en">
    <head>
        <meta charset=utf-8/>
    </head>
    <body>
        <div id='player'>
                    <video width="352" height="198" controls>
                    <source src="https://[subscription].api.retailnext.net/v1/hls/[video_channel_uuid].m3u8?token=[token_value]"
                    type="application/x-mpegURL">
                    </video>
        </div>
        <script>
            var player = videojs('my_video_1');
            player.play();
            </script>
    </body>
</html>

curl -viL --basic --user <AccessKey>:<SecretKey> \
 -XGET "https://<subscription>.api.retailnext.net/v1/downloads/list?prefix=custom_exports"

{
    {
        "files": [
            "custom_exports/inventory_reports/05944972-c87a-11ed-8c56-8000cc4953f8.csv",
            "custom_exports/inventory_reports/0f3d98f2-c87a-11ed-881d-00002a6c38b8.csv",
            "custom_exports/inventory_reports/1192b1f0-c87a-11ed-981f-8000f32a2173.csv",
            "custom_exports/inventory_reports/a75ae7e6-c881-11ed-8abf-8000de483b7d.csv",
            "custom_exports/inventory_reports/ae16b536-c86a-11ed-887c-0000385b4561.csv",
            "custom_exports/inventory_reports/b0cbaab8-c877-11ed-883f-c000a60cf1fb.csv",
            "custom_exports/inventory_reports/bf6b39f8-c877-11ed-84fa-c000a5796d57.csv",
            "custom_exports/inventory_reports/c5309b90-c867-11ed-8e58-00008aaf3e1d.csv",
            "custom_exports/inventory_reports/f9f37dfa-c878-11ed-8a55-4000f24c4b9b.csv",
            "custom_exports/inventory_reports/ffb34f5e-c878-11ed-8dbd-80001a064ed1.csv"
        ]
    }
}

curl -viL --basic --user <AccessKey>:<SecretKey> \
 -XGET "https://<subscription>.api.retailnext.net/v1/downloads/download?file=custom_exports/inventory_reports/05944972-c87a-11ed-8c56-8000cc4953f8.csv" 

[file content]

• Custom exports are only available for subscriptions upon request.

• To access custom exports, the associated setting in Admin > Advanced Settings must be enabled.

• The token used for accessing the API must have the associated user profile permission: “Access custom exports via API and SFTP” and the location profile: “All locations” for authorization.