Stores
API endpoint to get information about Store entities along with info on how to format Store POST request via async-job
Retrieve Stores Data
Creating, Deleted, and Updating stores
POST
Creating, Deleting, and Updating stores in Trax is done asynchronously. The stores POST should be done via the async jobs framework using the information below
Store Update Operation Details
Operations are done in an "update + insert" style:
-
In order to add a new store:
-
Add an object/row with all the required fields. The operation will succeed only if all the mandatory fields will be provided
-
-
In order to update a store:
-
Add an object/row with all the required fields. The operation will succeed only if all the mandatory fields will be provided
-
The unique identifier of a store is the 'store_number' field. This field is not editable
-
Empty field values will be treated as setting a field value to null
-
-
In order to delete a store:
-
Add an object/row with the store_number of the store, which serves as a unique identifier, and in addition to the rest of the mandatory fields
-
Set the 'is_deleted' value to true
-
Note that setting a store to 'is_active: false' does not delete the store
-
Request Example
Assume that Trax already contains valid data for 3 stores, with identifiers 200,300,400 (according to their store_number value), and without any data other than the mandatory fields.
In the JSON and CSV examples below, the following effect will occur on the data that is stores in Trax:
-
Store 100 will be added. Note that all mandatory fields are listed
-
Store 200 will be updated, and its "is_active" value will be set to "false"
-
Store 300 will be deleted
-
Store 400 will be updated, and its "manager_email" field will be set to "test@example.com"
Store POST Request File Fields
Mandatory fields marked indicated by
Please note that some other fields might be configured to be mandatory for your project. To get an exhaustive list of mandatory fields please contact Trax.
*
store_number string (100) *
The client's store unique identifier
store_name string (100) *
Name of the store
store_display_name string (100)
A display (short-version) name of the store for report use (for Trax output solutions)
store_type_name string (100)
Store Type - Store types that have been implemented from the client to Trax
region_name string (45) *
Region name - Region names that have been implemented from the client to Trax
district_name string (200)
District name: District names that have been implemented from the client to Trax
branch_name string (200)
Branch name: Branch names that have been implemented from the client to Trax
retailer_name string (100)
Retailer name: Retailer names that have been implemented from the client to Trax
state_code string (50)
ISO Code for state or province - State codes that have been implemented from the client to Trax
street string (200) *
Address street info e.g. "65 Chulia Street"
city string (100) *
Address info
postal_code string (45)
Address info
latitude Number (Float 10,6)
GPS latitude coordinate (in degrees)
longitude Number (Float 10,6)
GPS longitude coordinate (in degrees)
is_active Boolean
Indicates whether the store is active or has been deactivated. Optional values 'true' or 'false'
(Settings this value to 'false' will remove the store from the Trax Mobile Application. It will still appear in Trax reports) - default value is 'true'
manager_name string (45)
Name of the store's manager (or another contact person for the store)
manager_email string (100)
Email of the store's manager
manager_phone string (45)
Phone number of the store's manager
is_deleted Boolean
True - delete the store
False - remove the delete flag (By default false)
additional_attributes Object (varchar(100))
In addition to the attributes above, it is possible to add additional attributes for stores (currently, Trax supports up to 45 key-value pairs)
Request Example - CSV
store_number,store_name,store_type_name,region_name,street,city,is_active,is_deleted,manager_email 100,sample store A,Modern Trade,Northwest,65 Chulia Street,New Mexico,,,
200,sample store B,Traditional Trade,Northwest,66 Chulia Street,New Mexico,false,,
300,sample store C,Standard Trade,Northwest,67 Chulia Street,New Mexico,,true,
400,sample store D,Traditional Trade,Northwest,68 Chulia Street,New Mexico,,,test@example.com
Request Example - JSON
[
{
"store_number" : "100",
"store_name" : "sample store A",
"store_type_name" : "Modern Trade",
"region_name" : "Northwest",
"street" : "65 Chulia Street",
"city" : "New Mexico"
},
{
"store_number" : "200",
"store_name" : "sample store B",
"store_type_name" : "Traditional Trade",
"region_name" : "Northwest",
"street" : "66 Chulia Street",
"city" : "New Mexico", "is_active" : false
},
{
"store_number" : "300",
"store_name" : "sample store C",
"store_type_name" : "Standard Trade",
"region_name" : "Northwest",
"street" : "67 Chulia Street",
"city" : "New Mexico",
"is_deleted" : true
},
{
"store_number" : "400",
"store_name" : "sample store D",
"store_type_name" : "Traditional Trade",
"region_name" : "Northwest",
"street" : "68 Chulia Street",
"city" : "New Mexico",
"manager_email" : "test@example.com"
}
]
GET
Supported Protocol: HTTPS
GET /api/:version_number/:project_name/entity/store?:pagination_params
curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/api/v4/my-project/entity/store?sort=store_number&page=1&per_page=10
metadata object
Info related to pagination
store Object[]
List of stores, each containing the following fields:
store_number string
The Client's store unique identifier
store_name string
Name of the Store
store_display_name string
A display (short-version) name of the store for report use (for Trax output solutions)
store_type_name string
Store type (Store types that have been configured in coordination with the Trax implementation team)
region_name string
Region name (Region names that have been configured in coordination with Trax implementation team)
district_name string
District name (District names that have been configured in coordination with Trax implementation team)
branch_name string
branch name (branch names that have been configured in coordination with Trax implementation team)
retailer_name string
Retailer name (Retailer names that have been configured in coordination with Trax implementation team)
state_code string
ISO code for state or province (State codes that have been configured in coordination with Trax implementation team)
street string
Address street info (e.g. 65 Chulia Street)
city string
Address info
postal_code string
Address info
latitude number (Float 10,6)
GPS latitude coordinate (in degrees)
longitude number (Float 10,6)
GPS longitude coordinate (in degrees)
is_active boolean
Indicates whether the store is active or has been deactivated
(Setting this value to 'false' will remove the store from Trax Mobile Application. It will still appear in Trax's reports)
manager_name string
Name of the store's manager (or another contact person for the store)
manager_email string
Email of the store's manager
manager_phone string
Phone number of the store's manager
last_updated_time number
(Epoch Unix Time timestamp)
The store's last update time in Epoch Unix Time timestamp
is_deleted boolean
Is the store deleted (True or False)
additional_attributes object (varchar(100))
In addition to the attributes above, it is possible to add additional attributes for stores (currently Trax supports up to 45 name-value pairs)
Request Details
Mandatory fields marked indicated by
*
{
"metadata": {
"page": 2,
"per_page": "10",
"page_count": 1167,
"total_count": 11668,
"links": {
"self": "/api/v4/my-project/entity/store?sort=store_number&page=1&per_page=10",
"first": "/api/v4/my-project/entity/store?sort=store_number&page=0per_page=10",
"previous": "/api/v4/my-project/entity/store?sort=store_number&page=0&per_page=10",
"next": "/api/v4/my-project/entity/store?sort=store_number&page=2&per_page=10",
"last": "/api/v4/my-project/entity/store?sort=store_number&page=1166&per_page=10",
}
},
"stores": [
{
"store_number": "100050000000008",
"store_name": "My Store 100050000000008",
"store_display_name": "My Store 100050000000008",
"store_type_name": "MY store type",
"street": "My Street",
"city": "My City",
"postal_code": "12345",
"latitude": 1.357393,
"longitude": 103.811349,
"is_active": true,
"manager_name": "Manager Name",
"is_deleted": false,
"manager_phone": "+12345671234567",
"manager_email": "managername@my_mail.com",
"last_update_time": "2017-03-15 16:10:03",
"region_name": "Singapore",
... }
],
...
}
}
Response
Response Details
The Store GET reply body will contain the following fields
Validation and Errors
The following are the validations and errors that may appear due to an invalid GET request:
Unknown Field
-
Error Code: 400 - Bad Request
-
Error: Unknown Field: <field_name>
Internal Server Error
-
Error Code: 500 - Internal Server Error
-
Error: Trax Internal Error
Incorrect or expired token
-
Error Code: 401 - Unauthorized
-
Error: Incorrect or expired token
Requesting a forbidden resource
-
Error Code: 403 - Forbidden
-
Error: A forbidden resource has been requested <resource>
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Query Parameters
version_number string *
The current implemented API version. <Major> version (e.g. 'v4')
project_name string *
Project name as provided by Trax
pagination params
For more info see the pagination page. By default the first page will be returned first
Response, Validation, and Errors
The initial response for a valid async job request will be 202 Accepted.
When the async job is queried, a the outcome of the job will be available only when the status is 'done'.
For more info, see the Async-Jobs page
Validation and Error File
When uploading the file, the Trax system runs numerous validations on the file to confirm it has all the necessary fields.
Should there be issues with the file, an error file will be generated. This file is provided in both JSON and XLS format. Each entry with an error will contain the store number with the error and will contain max 3 errors per row/record. It will also contain one or several of the following errors based on failing the related validation:
Error Object File Fields
store_number string
Identifier of the store
errors array (string)
Errors associated with the store_number, see below for list
Error types
Mandatory Variables - Missing Mandatory
Fields During creation
-
Missing mandatory field:<field_name>
-
Missing mandatory fields:
<field_name>,<field_name>....
Variable Types
-
Invalid variable type:<field_name>-expected type: <expected_variable_type>
-
Invalid variable types:<field_name>-expected type: <expected_variable_type>,
<field_name>-expected type: <expected_variable_type>...
Incorrect Format - Email Format will be validated
-
Incorrect format for field: <field_name>, the correct format: <correct_format>
Lookup Value does not exist, Unknown Value
-
Unknown <Look Up Type> '<Look Up Value>'
-
Example: Unknown Store <request_store_identifier>
(store_number as referenced in store_numbers)
-
Error File Example
[
{
"store_number": "100",
"errors": [ "Unknown store_type_name:Modern Trade"]
},
{
"store_number": "200",
"errors": [ "Unknown store_type_name: Traditional Trade"]
}
]