About Stores
Placeholder
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"
GET
Request
Supported Protocol: HTTPS
Mandatory Fields Marked indicated by
*
Query Parameters
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
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
Request Details
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
Response Details
Response Body
The Store GET reply body will contain the following fields
metadata object
Info related to pagination
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
In addition to the attributes above, it is possible to add additional attributes for stores (currently Trax supports up to 45 name-value pairs)
{
"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 Example
*
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
In addition to the attributes above, it is possible to add additional attributes for stores (currently, Trax supports up to 45 key-value pairs)
Store Update Fields
Mandatory Fields Marked indicated by
Response Details
The response for a valid async-job POST will be 202 Accepted. The result of the job will only be available when the job status is 'done'
See the Pagination page for more information for async-job status response
Error File
If there is an error parsing the file uploaded in the async-job, the response will include a file showing the fields with errors.
The file consists of an array of objects where each object is the error related to a particular store. A given object will include the following fields
Error Object File Fields
store_number string
Identifier of the store
errors array (string)
Errors associated with the store_number
Error File Example
[
{
"store_number": "100",
"errors": [ "Unknown store_type_name:Modern Trade"]
},
{
"store_number": "200",
"errors": [ "Unknown store_type_name: Traditional Trade"]
}
]
CSV Example
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
JSON Example
[
{
"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"
}
]