top of page

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:

 

  1. Store 100 will be added. Note that all mandatory fields are listed

  2. Store 200 will be updated, and its "is_active" value will be set to "false" 

  3. Store 300 will be deleted

  4. 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"]

  }

]

bottom of page