Platform API Endpoint: Retrieve Organisation Data

Within the SQUIZZ.com Application Programming Interface (API) it contains an endpoint that allows one organisation using 3rd party software to retrieve data from another connected organisation, who has imported and stored their data on the platform. This data could be products, pricing, stock availability, among many others. The "Retrieve Organisation Data" endpoint can be used to automate a number of processes, including the sharing of data between different organisations, and regularly keeping data up to date. To use the API endpoint you will need to have knowledge in building software applications, and how to make requests over the internet to call RESTful web services, which the platform's API endpoint is based on.

Topics

  1. Prerequisites
  2. Overview
  3. Retrieve Attributes and Product Attribute Value Data
  4. Retrieve Category Data
  5. Retrieve Maker data
  6. Retrieve Maker Model Data
  7. Retrieve Maker Model Mapping Data
  8. Retrieve Product Data
  9. Retrieve Product Pricing Data
  10. Retrieve Product Stock Quantity Data

Overview

The endpoint allows different kinds of organisational data to be retrieved from another chosen organisation who had previously imported their data into the platform. The endpoint will return a list of records in a conforming Ecommerce Standards document that will be formatted in a JSON HTTP response. For example the endpoint could be called to get a list of products from a supplying organisation, or get a list of stock quantities for the products that a supplier organisation sells. See the list below of the kinds of data that can be retrieved.

Organisations who are supplying the data can control the kinds data that is available to other organisations through the use of "Data Sharing Policies". For example one organisation may not allow another organisation to retrieve stock quantities, but may allow the retrieving organisation to get product pricing data. Data sharing policies may also be used to restrict the kinds of products that another organisation may retrieve.

The endpoint allows a maximum of 5000 records to be retrieved in one request. Where there are more than 5000 records to retrieve the calling software can use the "records_start_index" and "records_max_amount" parameters to step through and download the a range of records across multiple requests.

Before using this endpoint we recommend that you understand what the Ecommerce Standards Documents are and how you can read data from the standards into your own business logic. Note that there are trading token costs to retrieve the organisation data using this API. These costs may be paid by the organisation supplying the data, or the organisation retrieving the data depending on the data sharing policy that the supplying organisation has set up. See Trading Tokens and Pricing for information on costs.

HTTP Request

HTTP Method GET
HTTP URL https://api.squizz.com/rest/1/org/retrieve_esd/session_id
Parameters Data Type Mandatory Description
session_id STRING Yes ID of the API session. Place the session ID within the URL
supplier_org_id STRING Yes ID of the organisation issued by the platform to retrieve the data from.
data_type_id INTEGER Yes ID of the type of data to retrieve. Set one of the numbers:
records_start_index INTEGER No The index to start retrieving the records from. For example if there are 8000 product records, setting the record_start_index to 2000 will get records numbered 2000 onwards. If the parameter is not set then the start index is set to 0.
records_max_amount INTEGER No Sets the maximum amount of records that are returned. For example if set to 1000 then only up to 1000 records will be returned by the endpoint. If the parameter is not set or the value is higher than 5000 then the parameter will be set to 5000.
customer_account_code STRING Conditional Code of the supplying organisation's customer account. The account code is only required when the "data_type_id" is set to 37 to retrieve Customer Account Product Pricing, and if the supplying organisation has assigned multiple customer accounts to the organisation calling the endpoint. The customer account code will dictate how the products are priced.

 

HTTP Response

Response Data Type JSON
     
Parameters Data Type Description
result ENUM (SUCCESS or FAILURE) Either "SUCCESS" or "FAILURE". If successful then the data was successfully retrieved.
resultStatus INTEGER
  • Set to 1 of the data was successfully obtained
  • Set to 2 of the data could not be obtained
version DECIMAL Version of the Ecommerce Standards Document being returned from the server.
configs.api_version DECIMAL Version of the SQUIZZ.com platform's API used to handle the request
configs.result_code STRING

Status code of trying to retrieve the organisation's data. The following codes could be returned:

  • SERVER_SUCCESS
    The record data was successfully obtained.
     
  • SERVER_ERROR_ORG_DOES_NOT_EXIST
    The organisation supplying the data with the given organisation ID could not be found or is not active within the platform. Check with the supplier organisation that their organisation ID issued by the platform is correct.
     
  • SERVER_ERROR_SESSION_INVALID
    The session used to call the endpoint has expired, or never existed. Look at calling the Create Session endpoint to get another session ID.
     
  • SERVER_ERROR_NO_ORG_CUSTOMER_ACCOUNT_SET
    No customer account has been provided when calling the endpoint to obtain pricing data, or the customer account provided does not match the account that the organisation who is supplying the data has assigned.
     
  • SERVER_ERROR_NO_ORG_CUSTOMER_ACCOUNT_ASSIGNED
    The organisation supplying the pricing data has not assigned any customer account to the customer organisation. The supplier organiation needs to do so to allow pricing data to be obtained.
     
  • SERVER_ERROR_ORG_CANNOT_BE_FOUND
    The organisation supplying the data with the given organisation ID could not be found or is not active within the platform or otherwise no connection exists between the two organisations.
     
  • SERVER_ERROR_PERMISSION_DENIED
    The organisation calling the endpoint does not have permission to obtain the kind of data requested from the organisation supplying the data.
     
  • SERVER_ERROR_ORG_NOT_ENOUGH_CREDITS
    Either the organisation supplying the data, or the organisation retrieving the data does not have enough trading tokens within the platform to pay for the data retrieval. Check that either organisation has enough trading tokens to cover retrieving the data.
     
  • SERVER_ERROR_UNKOWN
    An unspecified or unexpected error has occurred on the server when calling the endpoint. If this error continues to be returned please raise the issue with SQUIZZ.com.
configs.recordsStartIndex INTEGER The start index of the record that records were returned from
configs.recordsMaxAmount INTEGER The maximum amount of records that have been returned by the endpoint
configs.dataFields CSV Contains a list of comma separated values containing the fields that are included in the record data being exported. If the field is displayed in this CSV list but the record does not contain the field in the dataRecords array, then it denotes that the record is using the default value of the field.
dataRecords JSON ARRAY

List of records based on the data type set in the request:

  • If the Data Type ID is set to 3 then returns a list of Product Ecommerce Standards Records. Each record contains details of a product.
  • If the Data Type ID is set to 37 then returns a list of Price Ecommerce Standards Records. The pricing records contains both unit and quantity break pricing for each of the products the requesting organisation can buy products at, based on its relationship with the organisation supplying the data.
  • If the Data Type ID is set to 10 then returns a list of Stock Quantity Ecommerce Standards Records. Each stock quantity record defines the amount of product stock that is available by the organisation supplying the stock.
  • If the Data Type ID is set to 8 then returns a list of Category Ecommerce Standards Records. Each category record defines a grouping of products and categories assigned to it
  • If the Data Type ID is set to 11 then returns a list of Attribute Profile Records, as well as a list of product Attribute Value Records. Each attribute profile groups a list of attributes together, with each attribute defining a single type of data that can have many values set against it. Each product attribute value record contains an attribute's value assigned to a product, allowing many additional pieces of data to be assigned to products, such as specifications or other details. Attribute profiles and product attribute values allows products to have an unlimited amount of additional fields defined against them, with different kind of fields set for different kinds of products.
  • If the Data Type ID is set to 44 then returns a list of Maker Records. Each maker (also known as a manufacturer) defines an organisation or person who manufactures or assembles materials and parts together to make complete models of products.
  • If the Data Type ID is set to 45 then returns a list of Maker Model Records. Each Maker Model defines a model that has been created by a manufacturer. A model may consist of many products that may or may not contain interchangable products that an organisation may offer. Each model may contain a list of Attribute Value Records assigned to it that define additional details, based on the kind of model that it is. For instance a vehicle model may contain attributes that define its engine size, colours it comes in, or size of its fuel tank. Example types of models include vehicles, printers, mobile devices, computers, toys, and much more.
  • If the Data Type ID is set to 46 then returns a list of Maker Model Mapping Records. Each Maker Model Mapping record defines a product being assigned to a model in a given category. These records define which of the organisation's products can be assigned to different categories across many models. Each mapping record may specify the quantity of a product that is required for a model. Each mapping record may also contain a list of Attribute Value Records that defines additional information about a product when specifically assigned to a category in the model.

 

HTTP Response Example:

{"result":"SUCCESS", "version":"1.0", "configs":{"dataFields":"comma,list,of,record,fields,being,exported", "api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS", "recordsStartIndex":"0", "recordsMaxAmount":"5000"}, "dataRecords":[list_of_esd_records]}

Retrieve Attributes and Product Attribute Value Data

The Retrieve Organisation Data endpoint can be called by an organisation to retrieve a list of attribute data from another organisation connected to it on the SQUIZZ.com platform. The endpoint will return a list of attribute profiles, attributes and product attribute value records in the Attribute Ecommerce Standards Document (ESD) JSON data format that the receiving organisation has been given access to download, based on the Data Sharing Policy that the supplying organisation has assigned to the receiving organisation.

Within the retrieved Attribute JSON document, it is broken up into 2 parts. The first being a list of attribute profile records that each contain a list of attributes. Each attribute profile record conforms to the Attribute Profile ESD Record format, and then each attribute record conforms to the Attribute ESD Record format.

The second part of the Attribute JSON document contains a list of attribute values set against each product  Each product attribute value record is conforms to the Attribute Value ESD Record format. 

Attributes effectively allow an unlimited number of additional fields to be defined for products and models, with multiple product or model values being set for each attribute. Attributes are grouped into attribute profiles, allowing multiple attribute fields to be given a greater context of what they store or represent. The following table shows the record fields that this endpoint in the SQUIZZ.com API supports:

Data Type Attribute Profile
Field Name Data Type Mandatory Default Value Description
keyAttributeProfileID STRING Yes [EMPTY STRING] Unique identifier of the attribute profile that the supplier organisation has set, ensuring that only one attribute profile has this key identifier across all its profiles. The keyAttributeProfileID may be created by a person, or may be based on a internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier.
internalID STRING Yes [EMPTY STRING] This field stores the unique ID that the SQUIZZ.com platform generated when the attribute profile was imported into the platform.
name STRING No [EMPTY STRING] Name of the attribute profile. The name typically contains natural words that allow it easily recognised and understood by people. The name may broadly indicate all the types of attributes assigned to it.
description STRING No [EMPTY STRING] Text that provides more in depth details about what the attribute profile is or represents.
attributes Attribute ARRAY No [Null Value] An array of attributes that each define one type of data or field that values can be stored against.
Attribute Record Fields
keyAttributeID STRING Yes [EMPTY STRING] Unique identifier of the attribute that the supplier organisation has set, ensuring that only one attribute has this key identifier across all its attributes. The keyAttributeID may be created by a person, or may be based on a internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier.
name STRING No [EMPTY STRING] Name of the attribute. The name typically contains natural words that allow it easily recognised and understood by people. The name would typically indicate the kind of data/values that could be stored against it.
dataType ENUM(STRING, NUMBER) Yes 'STRING' Controls the type of values that are allowed to be stored against the attribute. If set to STRING then any text characters may be set in the attribute's values. If set to NUMBER then only numbers and decimals may be placed into the values stored against the attribute.
Product Attribute Value Record Fields
keyAttributeID STRING Yes [EMPTY STRING] Key identifier of the attribute record that the attribute value has its value assigned against.
keyAttributeProfileID STRING Yes [EMPTY STRING] Key identifier of the attribute profile that the attribute value is assigned against belongs to.
numberValue DECIMAL No 0 Contains the product's attribute value when the attribute specifies that its value is stored as a numeric number. The number can only contain the characters 0 to 9, and decimals.
stringValue STRING No [EMPTY STRING] Contains the product's attribute value when the attribute specifies that its value is stored as a string value. The value may contain any types of characters.

HTTP Request Raw Example:

GET https://api.squizz.com/rest/1/org/retrieve_esd/3042EXAMPLEGSESSIONID342?supplier_org_id=1302EXAMPLEORGID&data_type_id=11 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

HTTP Response Example:

Below is an example Attribute Document returned by the API endpoint.

{
 "version": 1.3,
 "resultStatus": 1,
 "dataTransferMode": "COMPLETE",
 "totalDataRecords": 4,
 "message":"The product attribute data has been successfully obtained.",
 "configs":{},
 "attributeProfiles":
 [
  {
   "keyAttributeProfileID":"PAP-001"
  },
  {
   "keyAttributeProfileID":"PAP002",
   "name":"Clothing Styling",
   "description":"View the styling details of clothes",
   "attributes":
   [
    {
     "keyAttributeID":"PAP002-0"
    },
    {
     "keyAttributeID":"PAP002-1",
     "name":"Colour"
    },
    {
     "keyAttributeID":"PAP002-2",
     "name":"Size",
     "dataType":"NUMBER"
    },
    {
     "keyAttributeID":"PAP002-3",
     "name":"Texture",
     "dataType":"STRING"
    }
   ]
  }
 ],
 "dataRecords":
  [
  {
   "keyProductID":"PROD-001",
   "keyAttributeProfileID":"PAP002",
   "keyAttributeID":"PAP002-0"
  },
  {
   "keyProductID":"PROD-001",
   "keyAttributeProfileID":"PAP002",
   "keyAttributeID":"PAP002-1",
   "stringValue":"RED"
  },
  {
   "keyProductID":"PROD-001",
   "keyAttributeProfileID":"PAP002",
   "keyAttributeID":"PAP002-2",
   "numberValue": 8
  },
  {
   "keyProductID":"PROD-001",
   "keyAttributeProfileID":"PAP002",
   "keyAttributeID":"PAP002-3",
   "stringValue": "soft"
  }
 ]
}

Tips and Recommendations:

  • If possible call the endpoint using the SQUIZZ.com API's native programming language libraries to cut down on the amount of development work needed to retrieve the product data. See API Native Programming Libraries.
  • When the attribute document is being returned from the API, in each of the attribute profile or attribute value records, in any fields that had the default value set may be omitted from being included in the returned JSON. This cuts down on the amount of redundant JSON data that needs to be downloaded, speeding up retrieval times.
  • Call the API endpoint to retrieve product data from a supplier organisation first, then use the product data in conjunction with the subsequent retrieved product attribute value data to gain additional information about each product assigned to the each attribute value record. Doing it this way avoids duplicate maker data being repeatedly downloaded with every model record, speeding up data retrieval times.
  • Call the API endpoint to retrieve attributes data from a supplier organisation first, then use the attribute data in conjunction with the subsequent retrieved model data to gain additional information about each attribute and attribute profile the model attribute values are assigned to. This also avoids retrieving duplicate information about attributes and attribute profiles, speeding up data retrieval times.
  • Note that there are trading token costs to call the endpoint. The supplying organisation may subsidise these costs, based on the data sharing policy assigned to the retrieving organisation. For more details on costs see Trading Tokens and Pricing for more details.

Retrieve Category Data

The Retrieve Organisation Data endpoint can be called by an organisation to retrieve a list of categories from another organisation connected to it on the SQUIZZ.com platform, as well as the products that are assigned to each category. The endpoint will return a list of category records in the Category Ecommerce Standards Document(ESD) JSON data format that the receiving organisation has been given access to download, based on the Data Sharing Policy that the supplying organisation has assigned to the receiving organisation.

Within the retrieved Category JSON document, each category record is conforms to the Category ESD Record format. The following table shows the record fields that this endpoint in the SQUIZZ.com API supports:

Data Type Category
Field Name Data Type Mandatory Default Value Description
keyCategoryID STRING Yes [EMPTY STRING] Unique identifier of the category that the supplier organisation has set, ensuring that only one category has this key identifier across all its categories. The keyCategoryID may be the same as the category code, or may be based on a different internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier.
keyCategoryTreeID STRING No [EMPTY STRING] Key identifier of the categories that the category belongs to or can be found within.
keyCategoryParentID STRING No [EMPTY STRING] Links the category to another that is its parent within a category tree. Is set the keyCategoryID of another category.
internalID STRING Yes [EMPTY STRING] This field stores the unique ID that the SQUIZZ.com platform generated when the category was imported into the platform.
name STRING No [EMPTY STRING] Name of the category. The name typically contains natural words that allow it easily recognised and understood by people, and the types of products it may represent.
categoryCode STRING No [EMPTY STRING] Code that allows the category to be identified. Typically this code is unique to each category that the supplier organisation has.
metaTitle STRING No [EMPTY STRING] The meta title contains a label of the category, that may be embedded within web pages. The meta title may be used by search engine software to rank the category and its relevancy.
metaKeywords STRING No [EMPTY STRING] The meta keywords may contain words that describe the category, and may be embedded within web pages. The meta keywords may be used by search engine software to rank the category and its relevancy.
metaDescription STRING No [EMPTY STRING] The meta description may contain text that describe the category, that may be embedded within web pages. The meta description may be used by search engine software to rank the category and its relevancy.
ordering INTEGER No 0 Number to order the category by. This may be used to order a number of categories in a hierarchical tree that are all assigned to the same parent category.
description1 STRING No [EMPTY STRING] First description of the category. May contain any information about the category, such as details of the kinds of products it represents, or other child categories.
description2 STRING No [EMPTY STRING] Second description of the category. May contain any information about the category, such as details of the kinds of products it represents, or other child categories.
description3 STRING No [EMPTY STRING] Third description of the category. May contain any information about the category, such as details of the kinds of products it represents, or other child categories.
description4 STRING No [EMPTY STRING] Fourth description of the category. May contain any information about the category, such as details of the kinds of products it represents, or other child categories.
keyProductIDs STRING ARRAY No [Null Value] An array of Key Product IDs that indicate the products that are assigned to the category, based on their key identifier. The products in the array are sorted in order that the products are assigned to the category.

HTTP Request Raw Example:

GET https://api.squizz.com/rest/1/org/retrieve_esd/3042EXAMPLEGSESSIONID342?supplier_org_id=1302EXAMPLEORGID&data_type_id=8 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

HTTP Response Example:

Below is an example Category Document returned by the API endpoint.

{
 "version": 1.3,
 "resultStatus": 1,
 "message":"The category data has been successfully obtained.",
 "dataTransferMode": "COMPLETE",
 "totalDataRecords": 3,
 "configs":{"dataFields":"keyCategoryID,categoryCode,keyCategoryParentID,name,description1,description2,description3,description4,metaTitle,metaKeywords,metaDescription,ordering"},
 "dataRecords":
  [
  {
   "keyCategoryID":"2",
   "categoryCode":"Home and Stationery"
  },
  {
   "keyCategoryID":"123",
   "categoryCode":"tables-chairs",
   "keyCategoryParentID":"2",
   "name":"Tables and Chairs",
   "description1":"View our extensive range of tables and chairs",
   "description2":"Range includes products from the ESD designers",
   "description3":"",
   "description4":"",
   "metaTitle":"Tables and Chairs From ESD Designers",
   "metaKeywords":"tables chairs esd furniture designers",
   "metaDescription":"Tables and chairs from the ESD designers",
   "ordering": 2,
   "keyProductIDs":["TAB-1","53432","CHAIR-5"]
  },
  {
   "keyCategoryID":"124",
   "categoryCode":"paper",
   "keyCategoryParentID":"2",
   "name":"Paper Products",
   "description1":"View our extensive range of paper",
   "description2":"Range includes paper only sources from sustainable environments",
   "description3":"",
   "description4":"",
   "metaTitle":"Paper Products",
   "metaKeywords":"paper products environmental",
   "metaDescription":"Paper products from sustainable environments",
   "ordering": 1,
   "keyProductIDs":["PROD-001","PROD-002"]
  }
 ]
}

Tips and Recommendations:

  • If possible call the endpoint using the SQUIZZ.com API's native programming language libraries to cut down on the amount of development work needed to retrieve the category data. See API Native Programming Libraries.
  • When the category document is being returned from the API, in each of the category records any fields that had the default value set may be omitted from being included in the returned JSON. This cuts down on the amount of redundant JSON data that needs to be downloaded, speeding up retrieval times.
  • Within the returned category document's configs property, the dataFields property will provide a list of all the record properties that can be expected to have data set for each category record. Then if a model field was not included in a record returned from the endpoint, then it can be presumed that its value would have been the default indicated in the table above.
  • If you are saving the retrieved category data to a database, use the list of category fields in the dataFields property to indicate which fields of existing category records in your database should be updated. This can be very useful to ensure that not all category fields are being overwritten in your database, allowing some category data to be updated from an external data source, and other category data be left alone.
  • Call the API endpoint to retrieve product data from a supplier organisation first, then use the product data in conjunction with the subsequent retrieved category data to gain additional information about each product assigned to the each category record. Doing it this way avoids duplicate product data being repeatedly downloaded with every category record, speeding up data retrieval times.
  • Note that there are trading token costs to call the endpoint. The supplying organisation may subsidise these costs, based on the data sharing policy assigned to the retrieving organisation. For more details on costs see Trading Tokens and Pricing for more details.

Retrieve Maker data

The Retrieve Organisation Data endpoint can be called by an organisation to retrieve a list of makers from another organisation connected to it on the SQUIZZ.com platform. The endpoint will return a list of maker records in the Makers Ecommerce Standards Document(ESD) JSON data format that the receiving organisation has been given access to download, based on the Data Sharing Policy that the supplying organisation has assigned to the receiving organisation.

Within the retrieved Makers JSON document, each maker record is conforms to the Maker ESD Record format. The following table shows the record fields that this endpoint in the SQUIZZ.com API supports:

Data Type Maker
Field Name Data Type Mandatory Default Value Description
keyMakerID STRING Yes [EMPTY STRING] Unique identifier of the maker that the supplier organisation has set, ensuring that only one maker has this key identifier across all its makers. The keyMakerID may be the same as the maker code, or may be based on an different internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier.
internalID STRING Yes [EMPTY STRING] This field stores the unique ID that the SQUIZZ.com platform generated when the maker was imported into the platform.
name STRING No [EMPTY STRING] Name of the maker. The name typically contains natural words that allow it easily recognised and understood by people on who the maker/manufacturer is.
makerCode STRING No [EMPTY STRING] Code that allows the maker to be identified. Typically this code is unique to each maker that the organisation utilises.
makerSearchCode STRING No [EMPTY STRING] Code that may be used by people to search for the maker and appears within web page URLs. The search code would have keywords that people would typically use to find the maker. The code may be made of several key words each split with a hyphen character. 
ordering DECIMAL No 0 A number that indicates how the the maker should be ordered within the list of makers.
groupClass STRING No [EMPTY STRING] Text that allows several makers to be grouped together based on a similar class of makers.
establishedDate LONG INTEGER No 0 Date that the maker first founded and established itself as a business. The date is stored as a long integer in milliseconds since the 1st January 1970 UTC epoch, also known as unix time.
orgName STRING No [EMPTY STRING] Name of the organisation that the maker represents or is associated to.
authorityNumbers STRING ARRAY No [EMPTY STRING ARRAY] An array that contains the number issued by a government authority to the maker's organisation. Typically this number would be issued by the government authority in the country where the organisation is established. For example in Australia this would be the Australian Business Number (ABN).
authorityNumberLabels STRING ARRAY No [EMPTY STRING ARRAY] List of labels set for the authority numbers. The array length is the same as the authorityNumbers property, or left empty
authorityNumberTypes INTEGER ARRAY No [EMPTY INTEGER ARRAY] List of authority number types matching the authority numbers. The number corresponds to the Ecommerce standards ESDocumentConstants that are prefixed with "AUTHORITY_NUM_". The array length is the same as the authorityNumbers property, or left empty.

HTTP Request Raw Example:

GET https://api.squizz.com/rest/1/org/retrieve_esd/3042EXAMPLEGSESSIONID342?supplier_org_id=1302EXAMPLEORGID&data_type_id=44 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

HTTP Response Example:

Below is an example Maker Document returned by the API endpoint.

{
 "version": 1.3,
 "resultStatus": 1,
 "message":"The maker data has been successfully obtained.",
 "dataTransferMode": "COMPLETE",
 "totalDataRecords": 2,
 "configs":{"dataFields":"keyMakerID,makerCode,name,makerSearchCode,groupClass,ordering,establishedDate,orgName,authorityNumbers,authorityNumberLabels,authorityNumberTypes"},
 "dataRecords":
  [
  {
   "keyMakerID":"2",
   "makerCode":"CAR1",
   "name":"Car Manufacturer A",
   "makerSearchCode":"Car-Manufacturer-A",
   "groupClass":"POPULAR CARS",
   "ordering": 2,
   "establishedDate": 1449132083084,
   "orgName":"Car Manufacturer A",
   "authorityNumbers":["123456789 1234"],
   "authorityNumberLabels":["Australian Business Number"],
   "authorityNumberTypes":[1]
  },
  {
   "keyMakerID":"3",
   "makerCode":"CAR3",
   "name":"Car Manufacturer B",
   "makerSearchCode":"Car-Manufacturer-B-Sedans-Wagons",
   "groupClass":"CUSTOM CARS",
   "ordering": 1,
   "establishedDate": 1449132083084,
   "orgName":"Car Manufacturer B",
   "authorityNumbers":["98877664322"],
   "authorityNumberLabels":["Australian Business Number"],
   "authorityNumberTypes":[1]
  }
 ]
}

Tips and Recommendations:

  • If possible call the endpoint using the SQUIZZ.com API's native programming language libraries to cut down on the amount of development work needed to retrieve the product data. See API Native Programming Libraries.
  • When the makers document is being returned from the API, in each of the makers records any fields that had the default value set may be omitted from being included in the returned JSON. This cuts down on the amount of redundant JSON data that needs to be downloaded, speeding up retrieval times.
  • Within the returned maker document's configs property, the dataFields property will provide a list of all the record properties that can be expected to have data set for each maker record. Then if a maker field was not included in a record returned from the endpoint, then it can be presumed that its value would have been the default indicated in the table above.
  • If you are saving the retrieved maker data to a database, use the list of maker fields in the dataFields property to indicate which fields of existing maker records in your database should be updated. This can be very useful to ensure that not all maker fields are being overwritten in your database, allowing some maker data to be updated from an external data source, and other maker data be left alone.
  • Note that there are trading token costs to call the endpoint. The supplying organisation may subsidise these costs, based on the data sharing policy assigned to the retrieving organisation. For more details on costs see Trading Tokens and Pricing for more details.

Retrieve Maker Model Data

The Retrieve Organisation Data endpoint can be called by an organisation to retrieve a list of maker models from another organisation connected to it on the SQUIZZ.com platform. The endpoint will return a list of model records in the Maker Model Ecommerce Standards Document(ESD) JSON data format that the receiving organisation has been given access to download, based on the Data Sharing Policy that the supplying organisation has assigned to the receiving organisation.

Within the retrieved Maker Model JSON document, each model record is conforms to the Maker Model ESD Record format. The following table shows the record fields that this endpoint in the SQUIZZ.com API supports:

Data TypeMaker Model
Field NameData TypeMandatoryDefault ValueDescription
keyMakerModelIDSTRINGYes[EMPTY STRING]Unique identifier of the maker model that the supplier organisation has set, ensuring that only one model has this key identifier across all its models. The keyMakerModelID may be the same as the model code, or may be based on a different internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier.
keyMakerIDSTRINGYes[EMPTY STRING]Key identifier of the maker that specifies the maker/manufacturer that the model belongs to or was manufactured by.
internalIDSTRINGYes[EMPTY STRING]This field stores the unique ID that the SQUIZZ.com platform generated when the model was imported into the platform.
nameSTRINGNo[EMPTY STRING]Name of the model. The name typically contains natural words that allow it easily recognised and understood by people.
modelCodeSTRINGNo[EMPTY STRING]Code that allows the model to be identified. Typically this code is unique to each maker model that the organisation contains.
modelSubCodeSTRINGNo[EMPTY STRING]Secondary code of the model which may be used further identify it.
modelSearchCodeSTRINGNo[EMPTY STRING]Code that may be used by people to search for the maker model and appears within web page URLs. The search code would have keywords that people would typically use to find the model. The code may be made of several key words each split with a hyphen character. 
groupClassSTRINGNo[EMPTY STRING]Text that allows several models to be grouped together based on a similar class of models.
createdDateLONG INTEGERNo0Date that the model was created. This date may be considered an internal date only relevant to the maker completing construction of the first model. Date is in the form of a number in milliseconds since the 01-01-1970 12:00am Epoch in UTC time-zone, also known as Unix date time.
releasedDateLONG INTEGERNo0Date that the model was released by the maker/manufacturer. This date may be designated by the maker as the official date that the model was first made available and known by. Date is in the form of a number in milliseconds since the 01-01-1970 12:00am Epoch in UTC time-zone, also known as Unix date time.
attributesAttribute Value ARRAYNo[Null Value]An array of attribute values that define additional data about the model. These attributes can contain data specific to each model, allowing for specialised data fields for different kinds of models to occur.
Attribute Value Record Fields
keyAttributeIDSTRINGYes[EMPTY STRING]Key identifier of the attribute record that the attribute value has its value assigned against.
keyAttributeProfileIDSTRINGYes[EMPTY STRING]Key identifier of the attribute profile that the attribute value is assigned against belongs to.
numberValueDECIMALNo0Contains the model's attribute value when the attribute specifies that its value is stored as a numeric number. The number can only contain the characters 0 to 9, and decimals.
stringValueSTRINGNo[EMPTY STRING]Contains the model's attribute value when the attribute specifies that its value is stored as a string value. The value may contain any types of characters.

HTTP Request Raw Example:

GET https://api.squizz.com/rest/1/org/retrieve_esd/3042EXAMPLEGSESSIONID342?supplier_org_id=1302EXAMPLEORGID&data_type_id=45 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

HTTP Response Example:

Below is an example Maker Model Document returned by the API endpoint.

{
 "version": 1.3,
 "resultStatus": 1,
 "message":"The model data has been successfully obtained.",
 "dataTransferMode": "COMPLETE",
 "totalDataRecords": 3,
 "configs":{"dataFields":"keyMakerModelID,keyMakerID,modelCode,modelSubCode,name,modelSearchCode,groupClass,releasedDate,createdDate,attributes"},
 "dataRecords":
  [
  {
   "keyMakerModelID":"1"
  },
  {
   "keyMakerModelID":"2",
   "keyMakerID":"2",
   "modelCode":"SEDAN1",
   "modelSubCode":"1ABC",
   "name":"Sahara Luxury Sedan 2016",
   "modelSearchCode":"Car-Manufacturer-A-Saraha-Luxury-Sedan-2016",
   "groupClass":"SEDAN",
   "releasedDate": 1456750800000,
   "createdDate": 1430748000000,
   "attributes":
   [
    {
     "keyAttributeProfileID":"MAKEMODELCAR",
     "keyAttributeID":"MMCAR-TYPE",
     "stringValue": "Sedan"
    },
    {
     "keyAttributeProfileID":"MAKEMODELCAR",
     "keyAttributeID":"MMCAR-ENGINE-CYLINDERS",
     "numberValue": 4
    },
    {
     "keyAttributeProfileID":"MAKEMODELCAR",
     "keyAttributeID":"MMCAR-FUEL-TANK-LITRES",
     "numberValue": 80.5
    }
   ]
  },
  {
   "keyMakerModelID":"3",
   "keyMakerID":"2",
   "modelCode":"TRUCK22",
   "modelSubCode":"EX",
   "name":"City Truck 2016",
   "modelSearchCode":"Car-Manufacturer-A-City-Truck-2016",
   "groupClass":TRUCK",
   "releasedDate": 1456750800000,
   "createdDate": 1430748000000,
   "attributes":
   [
    {
     "keyAttributeProfileID":"MAKEMODELCAR",
     "keyAttributeID":"MMCAR-TYPE",
     "stringValue": "Truck"
    },
    {
     "keyAttributeProfileID":"MAKEMODELCAR",
     "keyAttributeID":"MMCAR-ENGINE-CYLINDERS",
     "numberValue": 6
    },
    {
     "keyAttributeProfileID":"MAKEMODELCAR",
     "keyAttributeID":"MMCAR-FUEL-TANK-LITRES",
     "numberValue": 140
    }
   ]
  }
 ]
}

Tips and Recommendations:

  • If possible call the endpoint using the SQUIZZ.com API's native programming language libraries to cut down on the amount of development work needed to retrieve the product data. See API Native Programming Libraries.
  • When the maker model document is being returned from the API, in each of the model records any fields that had the default value set may be omitted from being included in the returned JSON. This cuts down on the amount of redundant JSON data that needs to be downloaded, speeding up retrieval times.
  • Within the returned model document's configs property, the dataFields property will provide a list of all the record properties that can be expected to have data set for each model record. Then if a model field was not included in a record returned from the endpoint, then it can be presumed that its value would have been the default indicated in the table above.
  • If you are saving the retrieved model data to a database, use the list of model fields in the dataFields property to indicate which fields of existing model records in your database should be updated. This can be very useful to ensure that not all model fields are being overwritten in your database, allowing some model data to be updated from an external data source, and other model data be left alone.
  • Call the API endpoint to retrieve maker data from a supplier organisation first, then use the maker data in conjunction with the subsequent retrieved model data to gain additional information about each maker assigned to the each model record. Doing it this way avoids duplicate maker data being repeatedly downloaded with every model record, speeding up data retrieval times.
  • Call the API endpoint to retrieve attributes data from a supplier organisation first, then use the attribute data in conjunction with the subsequent retrieved model data to gain additional information about each attribute and attribute profile the model attribute values are assigned to. This also avoids retrieving duplicate information about attributes and attribute profiles, speeding up data retrieval times.
  • Note that there are trading token costs to call the endpoint. The supplying organisation may subsidise these costs, based on the data sharing policy assigned to the retrieving organisation. For more details on costs see Trading Tokens and Pricing for more details.

Retrieve Maker Model Mapping Data

The Retrieve Organisation Data endpoint can be called by an organisation to retrieve a list of maker model mappings from another organisation connected to it on the SQUIZZ.com platform. Each Maker Model Mapping defines a product that belongs to a model and category. If a manufacturer builds a model that contains many interchangable parts, then an organisation may sell products that can be used/replaced/interchanged across many models. When an organisation maps each product to a model, it also must specify a category the a product is assigned to for the model. This allows categories of products to be assigned to each model, making it easier for people to see groups of products that each model contains, making it easier to find the products. When each product is mapped to a category and model, the quantity of products can also be set. This can indicate the quantity of products required for a part of the model.

The endpoint will return a list of maker model mapping records in the Maker Model Mapping Ecommerce Standards Document(ESD) JSON data format that the receiving organisation has been given access to download, based on the Data Sharing Policy that the supplying organisation has assigned to the receiving organisation.

Within the retrieved Maker Model Mapping JSON document, each model record is conforms to the Maker Model Mapping ESD Record format. The following table shows the record fields that this endpoint in the SQUIZZ.com API supports:

Data Type Maker Model Model
Field Name Data Type Mandatory Default Value Description
keyMakerModelID STRING Yes [EMPTY STRING] Key identifier of the maker model that defines the model that the product is assigned to.
keyProductID STRING Yes [EMPTY STRING] Key identifier of the product that denotes the product that the model is assigned to.
keyCategoryID STRING Yes [EMPTY STRING] Key identifier of the category that the product is assigned to for the specified model.
quantity DECIMAL No 0 Quantity of the product that is contained in the model for the specified category. The quantity refer's to the quantity of the product's base sell unit.
attributes Attribute Value ARRAY No [Null Value] An array of attribute values that define additional data about the model mapping. These attributes can contain data specific to each model mapping, allowing additional data about the particular product assigned to the category and model to be set.
Attribute Value Record Fields
keyAttributeID STRING Yes [EMPTY STRING] Key identifier of the attribute record that the attribute value has its value assigned against.
keyAttributeProfileID STRING Yes [EMPTY STRING] Key identifier of the attribute profile that the attribute value is assigned against belongs to.
numberValue DECIMAL No 0 Contains the model mapping's attribute value when the attribute specifies that its value is stored as a numeric number. The number can only contain the characters 0 to 9, and decimals.
stringValue STRING No [EMPTY STRING] Contains the model mapping's attribute value when the attribute specifies that its value is stored as a string value. The value may contain any types of characters.

HTTP Request Raw Example:

GET https://api.squizz.com/rest/1/org/retrieve_esd/3042EXAMPLEGSESSIONID342?supplier_org_id=1302EXAMPLEORGID&data_type_id=46 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

HTTP Response Example:

Below is an example Maker Model Mapping Document returned by the API endpoint.

{
 "version": 1.3,
 "resultStatus": 1,
 "message":"The maker-model-mapping data has been successfully obtained.",
 "dataTransferMode": "COMPLETE",
 "totalDataRecords": 3,
 "configs":{"dataFields":"keyMakerModelID,keyCategoryID,keyProductID,quantity,attributes"},
 "dataRecords":
  [
  {
   "keyMakerModelID":"2",
   "keyCategoryID":"CAR-TYRE",
   "keyProductID":"CAR-TYRE-LONG-LASTING",
   "quantity": 4,
   "attributes":
   [
    {
     "keyAttributeProfileID":"MAKEMODELCAR",
     "keyAttributeID":"MMCAR-WHEELSIZE-RADIUS-INCH",
     "numberValue": 21
    },
    {
     "keyAttributeProfileID":"MAKEMODELCAR",
     "keyAttributeID":"MMCAR-WHEELSIZE-TREAD",
     "stringValue": "All Weather"
    }
   ]
  },
  {
   "keyMakerModelID":"2",
   "keyCategoryID":"CAR-TYRE",
   "keyProductID":"CAR-TYRE-CHEAP",
   "quantity": 4,
   "attributes":
   [
    {
     "keyAttributeProfileID":"MAKEMODELCAR",
     "keyAttributeID":"MMCAR-WHEELSIZE-RADIUS-INCH",
     "numberValue": 20
    },
    {
     "keyAttributeProfileID":"MAKEMODELCAR",
     "keyAttributeID":"MMCAR-WHEELSIZE-TREAD",
     "stringValue": "BITUMEN"
    }
   ]
  }
 ]
}

Tips and Recommendations:

  • If possible call the endpoint using the SQUIZZ.com API's native programming language libraries to cut down on the amount of development work needed to retrieve the product data. See API Native Programming Libraries.
  • When the maker model mapping document is being returned from the API, in each of the model mapping records any fields that had the default value set may be omitted from being included in the returned JSON. This cuts down on the amount of redundant JSON data that needs to be downloaded, speeding up retrieval times.
  • Within the returned model mapping document's configs property, the dataFields property will provide a list of all the record properties that can be expected to have data set for each model mapping record. Then if a model field was not included in a record returned from the endpoint, then it can be presumed that its value would have been the default indicated in the table above.
  • If you are saving the retrieved model mapping data to a database, use the list of model mapping fields in the dataFields property to indicate which fields of existing model records in your database should be updated. This can be very useful to ensure that not all model mapping fields are being overwritten in your database, allowing some model mapping data to be updated from an external data source, and other model data be left alone.
  • Call the API endpoint to retrieve maker model data from a supplier organisation first, then use the maker model data in conjunction with the subsequent retrieved model mapping data to gain additional information about each model assigned to the each mapping record. Doing it this way avoids duplicate model data being repeatedly downloaded with every mapping record, speeding up data retrieval times.
  • Call the API endpoint to retrieve product data from a supplier organisation first, then use the product data in conjunction with the subsequent retrieved model mapping data to gain additional information about each product assigned to each mapping record. Doing it this way avoids duplicate product data being repeatedly downloaded with every mapping record, speeding up data retrieval times.
  • Call the API endpoint to retrieve category data from a supplier organisation first, then use the category data in conjunction with the subsequent retrieved model mapping data to gain additional information about each category assigned to each mapping record. Doing it this way avoids duplicate category data being repeatedly downloaded with every mapping record, speeding up data retrieval times.
  • Call the API endpoint to retrieve attributes data from a supplier organisation first, then use the attribute data in conjunction with the subsequent retrieved mapping data to gain additional information about each attribute and attribute profile the model mapping attribute values are assigned to. This also avoids retrieving duplicate information about attributes and attribute profiles, speeding up data retrieval times.
  • Note that there are trading token costs to call the endpoint. The supplying organisation may subsidise these costs, based on the data sharing policy assigned to the retrieving organisation. For more details on costs see Trading Tokens and Pricing for more details.

Retrieve Product Data

The Retrieve Organisation Data endpoint can be called by an organisation to retrieve a list of products from another organisation connected to it on the SQUIZZ.com platform. The endpoint will return a list of product records in the Products Ecommerce Standards Document(ESD) JSON data format that the receiving organisation has been given access to download, based on the Data Sharing Policy that the supplying organisation has assigned to the receiving organisation. The Data Sharing Policy will also control the data in specific product record fields that is available to the retrieving organisation. This can be used by the organisation supplying the product data to limit what kinds of data is available to each connected organisation.

Within the retrieved Products JSON document, each product record is conforms to the Products ESD Record format. The following table shows the record fields that this endpoint in the SQUIZZ.com API supports:

Data Type Product
Field Name Data Type Mandatory Default Value Description
keyProductID STRING Yes [EMPTY STRING] Unique identifier of the product that the supplier organisation has set, ensuring that only one product has this key identifier across all its products. The keyProductID may be the same as the product code, or may be based on an different internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier.
keyTaxcodeID STRING Yes [EMPTY STRING] The unique identifier of the taxcode that the supplier organisation has assigned to the product. The assigned taxcode is used to control how tax is applied to the product's pricing, or indicate how much tax was included in all of the product's prices if the pricing was set tax inclusive.
keySellUnitID STRING No [EMPTY STRING] The unique identifier of the default sell unit that the supplier organisation has assigned to the product.
internalID STRING Yes [EMPTY STRING] This field stores the unique ID that the SQUIZZ.com platform generated when the product was imported into the platform.
barcode STRING No [EMPTY STRING] Barcode that appears on the product or its packaging, allowing the product to be scanned and identified.
barcodeInner STRING No [EMPTY STRING] Code within the barcode that appears on the product or its packaging, allowing the product to be scanned and identified.
brand STRING No [EMPTY STRING] Name of the brand associated with the product, indicating how a market knows the product.
depth DECIMAL No 0 The physical depth measurement of each individual unit of the product, indicating how deep the product is.
description1 STRING No [EMPTY STRING] First description of the product. May contain any information about the product, such as how the product can be used, specifications, and any other detail.
description2 STRING No [EMPTY STRING] Second description of the product. May contain any information about the product, such as how the product can be used, specifications, and any other detail.
description3 STRING No [EMPTY STRING] Third description of the product. May contain any information about the product, such as how the product can be used, specifications, and any other detail.
description4 STRING No [EMPTY STRING] Fourth description of the product. May contain any information about the product, such as how the product can be used, specifications, and any other detail.
height Decimal No 0 The physical height measurement of each individual unit of the product, indicating how high the product stands.
isKitted ENUM(Y,N) No N Specifies if the product is made up by a number of component products that are bundled together to form a single kit.
isPriceTaxInclusive ENUM(Y,N) No N For any pricing set for the product, specifies if the pricing is exclusive of tax (does not include taxes) or tax has already been applied to the pricing (inclusive of taxes).
kitProductsSetsPrice ENUM(Y,N) No N If the product is marked as a product kit, then this denotes if the pricing of the product should be based on pricing directly set for it, or based on summing the pricing of the component products together.
name STRING No [EMPTY STRING] Name of the product. The name typically contains natural words that allow it easily recognised and understood by people on what the product is, or does.
productCode STRING No [EMPTY STRING] Code that allows the product to be identified. Typically this code is unique to each product that the organisation sells. The product code may also be known as a Stock Keeping Unit (SKU), item number, product ID, or item code in other systems.
productSearchCode STRING No [EMPTY STRING] Code that may be used by people to search for the product and appears within web page URLs. The search code would have keywords that people would typically use to find the product. The code may be made of several key words each split with a hyphen character. 
stockLowQuantity DECIMAL No 0 The amount of individual product base sell units that indicates when the product is low in stock. If the stock quantity contains a value that is higher than this field then the product stock level is considered "high", else if it is equal to or less than this field but greater than the stockNoneQuantity then the product's stock level is considered as "low".
stockNoneQuantity DECIMAL No 0 The amount of individual product base sell units that indicates when the product is out of stock. If the stock quantity contains a value equal to or less than this field then the product stock level is considered "out of stock".
Note that customers may still be allowed to purchase out-of-stock products, depending on if their assigned Data Sharing Policy allows them to do so or not via the "Back Order Purchased Products" permission.
stockQuantity DECIMAL No 0 The amount of individual base sell units of the product that the supplying organisation has in stock and makes available for purchase.
weight DECIMAL No 0 The physical weight measurement of each individual unit of the product, indicating how much the product weighs.
width DECIMAL No 0 The physical width measurement of each individual unit of the product, indicating how wide the product is.

HTTP Request Raw Example:

GET https://api.squizz.com/rest/1/org/retrieve_esd/3042EXAMPLEGSESSIONID342?supplier_org_id=1302EXAMPLEORGID&data_type_id=3 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

HTTP Response Example:

Below is an example Product Document returned by the API endpoint.

{
 "resultStatus":"1",
 "message":"The product data has been successfully obtained.",
 "configs":{"dataFields":"keyProductID,productCode,keyTaxcodeID,productSearchCode,barcode,barcodeInner,brand,name,description1,description2,description3,description4,productClass,keySellUnitID,weight,width,height,depth,stockQuantity,stockNoneQuantity,stockLowQuantity,stockLowQuantity,isPriceTaxInclusive,isKitted,kitProductsSetPrice"},
 "dataTransferMode": "COMPLETE",
 "version": 1.1,
 "totalDataRecords": 2,
 "dataRecords":
  [
  {
   "keyProductID":"123A",
   "productCode":"PROD-123",
   "keyTaxcodeID":"FREE"
   "internalID":"12341231ABCAV314123141BCA342",
  },
  {
   "keyProductID":"1234",
   "productCode":"PROD-001",
   "keyTaxcodeID":"GST",
   "internalID":"12341231ABCAV3141231412342",
   "productSearchCode":"Green-Recycled-Paper-Swisho",
   "barcode":"03423404230",
   "barcodeInner":"234234",
   "brand":"Swisho Paper",
   "name":"Swisho Green Paper",
   "description1":"Swisho green coloured paper is the ultimate green paper.",
   "description2":"Paper built strong and tough by Swisho",
   "description3":"Recommended to be used with dark inks.",
   "description4":"",
   "productClass":"paper",
   "weight": 20.1,
   "width": 21,
   "height": 29.7,
   "depth": 10,
   "stockQuantity": 200,
   "stockNoneQuantity": 0,
   "stockLowQuantity": 10,
   "isPriceTaxInclusive": "N",
   "isKitted":"N",
   "kitProductsSetPrice":"N",
   "keySellUnitID": 2,
  }
 ]
}

Tips and Recommendations:

  • If possible call the endpoint using the SQUIZZ.com API's native programming language libraries to cut down on the amount of development work needed to retrieve the product data. See API Native Programming Libraries.
  • When the product document is being returned from the API, in each of the product records any fields that had the default value set may be omitted from being included in the returned JSON. This cuts down on the amount of redundant JSON data that needs to be downloaded, speeding up retrieval times.
  • Within the returned product document's configs property, the dataFields property will provide a list of all the record properties that can be expected to have data set for each product record. Then if a product field was not included in a record returned from the endpoint, then it can be presumed that its value would have been the default indicated in the table above.
  • If you are saving the retrieved product data to a database, use the list of product fields in the dataFields property to indicate which fields of existing product records in your database should be updated. This can be very useful to ensure that not all product fields are being overwritten in your database, allowing some product data to be updated from an external data source, and other product data be left alone.
  • Call the API endpoint to retrieve product data from a supplier first, then use the product data in conjunction with obtaining product pricing data and product stock quantities to match the supplying organisation's products to pricing and stock availability.
  • Note that there are trading token costs to call the endpoint. The supplying organisation may subsidise these costs, based on the data sharing policy assigned to the retrieving organisation. For more details on costs see Trading Tokens and Pricing for more details.

Retrieve Product Pricing Data

The Retrieve Organisation Data endpoint can be called by an organisation to retrieve a list of product pricing from another organisation connected to it on the SQUIZZ.com platform. The endpoint will return a list of pricing records in the Price Ecommerce Standards Document(ESD) JSON data format that the receiving organisation has been given access to download, based on the Data Sharing Policy that the supplying organisation has assigned to the receiving organisation and customer account. The Data Sharing Policy will control which products are allowed to be retrieved. The customer account will determine the prices that the retrieving organisation is allowed to buy the supplying organisation's products for.

Within the retrieved Pricing JSON document, each price record is conforms to the Price ESD Record format. The following table shows the record fields that this endpoint in the SQUIZZ.com API supports:

Data Type Price
Field Name Data Type Mandatory Default Value Description
keyProductID STRING Yes [EMPTY STRING] Unique identifier of the product that the supplier organisation has set, ensuring that only one product has this key identifier across all of a supplier's products. The keyProductID may be the same as the product code, or may be based on an different internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier.
keySellUnitID STRING No NULL The unique identifier of the sell unit that the supplier organisation has set for the price of the product.
price DECIMAL Yes 0 The price set for the product against the assigned sell unit. The price will be set in the currency configured by the supplier organsiation. The price may be inclusive of tax or excluding tax, depending on the if the supplying organisation has set isPriceTaxInclusive against the product (found calling the endpoint to retreive Product data, see above section).
quantity DECIMAL No 0 The quantity of the product that needs to be purchased at for the price to apply. See below on how quantity break (also known as volume discounts) pricing rules work.
referenceID String No [EMPTY STRING] ID of the entity that the supplier organisation may have assigned against the product. The entity could be a contract, special price rule, promotion, or other object.
referenceType String No [EMPTY STRING]

Specifies the type of entity that the supplier organisation may have assigned against the product. Could be set to one of the prefixes:

  • C - Contract
  • CF - Contract Forced. Enforces the price of the product even if other cheaper quantity break prices exist.
  • P - Promotion.
TaxRate Decimal No NULL If set then explicitly defines the percentage of tax that the supplier organisation sets against the price. 

HTTP Request Raw Example:

GET https://api.squizz.com/rest/1/org/retrieve_esd/3042EXAMPLEGSESSIONID342?supplier_org_id=1302EXAMPLEORGID&data_type_id=37 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

HTTP Response Example:

Below is an example Price Document returned by the API endpoint.

{
 "resultStatus":"1",
 "message":"The product customer account pricing data has been successfully obtained.",
 "configs":
  {
   "dataFields":"keyProductID,keyAccountID,price,quantity,referenceID,referenceType",
   "quantity_break_direction":"EQUALABOVE'
  },
 "dataTransferMode": "COMPLETE",
 "version": 1.0,
 "totalDataRecords": 5,
 "dataRecords":
  [
  {
   "keyProductID":"PROD-123",
   "keySellUnitID":"EA",
   "price": 70.00,
   "quantity": 5
  },
  {
   "keyProductID":"PROD-123",
   "keySellUnitID":"EA",
   "price": 80.00,
   "quantity": 20,
   "referenceID": "FCONTRACT-1",
   "referenceType": "CF"
  },
  {
   "keyProductID":"PROD-123",
   "keySellUnitID":"EA",
   "price": 7.30,
   "quantity": 1,
   "referenceID": "CONTRACT-222",
   "referenceType": "C"
  },
  {
   "keyProductID":"PROD-456",
   "keySellUnitID":"EA",
   "price": 3.30,
   "taxRate": 10
  },
  {
   "keyProductID":"PROD-456",
   "keySellUnitID":"PACK",
   "price": 13.20
   "quantity": 6
  }
 ]
}

The above example would define the following pricing rules from its records:

  1. Buy 5 or more of product PROD-123 for $70.00 each
  2. Buy 20 or more of product PROD-123 for $80.00 each. On forced contract, ID: FCONTRACT-1
  3. Buy 1 or more of product PROD-123 for $75.30 each. On contract, ID: CONTRACT-222
  4. Buy 0 or more of product PROD-456 for $3.30 each
  5. Buy 6 or more of product PROD-456 for $13.20 per pack

Quantity Break/Volume Discount Pricing

When retrieving product pricing data from the endpoint it is possible that multiple prices could be returned for the same product for different quantities and sell units. This allows quantity breaks (also known as volume discount prices) to be made available by the supplier organisation. These quantity break prices may allow purchasing organisations to buy products for cheaper when more quantities are ordered. Each supplying organisation specifies the direction in which their quantity break prices become available, this is indicated in the returned pricing document by the value set in the "quantity_break_direction". This attribute can be set to one of the following values:

  • EQUALABOVE
    This allows pricing rules to be set up as:
    Buy 5 or more products Each for $10.00
    Buy 10 or more products Each for $8.00
     
  • EQUALBELOW
    This allows pricing rules to be set up as:
    Buy 5 or less products Each for $10.00
    Buy 10 or less products Each for $8.00
     
  • ABOVE
    This allows pricing rules to be set up as:
    Buy more than 5 products Each for $10.00
    Buy more than 10 products Each for $8.00
     
  • BELOW
    This allows pricing rules to be set up as:
    Buy 5 or less products Each for $10.00
    Buy 10 or less products Each for $8.00

When reading pricing data from the endpoint it is important the your software checks the "quantity_break_direction" attribute to ensure that it is correctly interpreting the quantity break prices.

Price Record Types

Each price record returned from the endpoint may define an entity that the supplier organisation has linked to it, this is set in the referenceID and referenceType fields. The referenceType can be set to one of the following:

  • C - Contract
    Denotes that the price is linked to a contract. The contract may define unique pricing setup up by the supplying organisation, based on pre-agreed terms or deals. Typically the referenceID field would store the ID of the contract.
     
  • CF - Contract With Forced Pricing
    Denotes that the price is linked to a contract. The contract may define unique pricing setup up by the supplying organisation, based on pre-agreed terms or deals. The contract defines pricing that will be priced for the product, even if it normally could be purchased for a cheaper price by another quantity break price. Typically the referenceID field would store the ID of the contract. This kind of contract typically locks in pricing for a period of time.
     
  • P - Promotion
    Denotes that the price is linked to a promotion. The promotion could be a sale order some other unique event that warrants a different price for the product. Promotions do not lock in prices.

It is important to check if a quantity break price is associated to a forced contract, or not, since the forced contract price may override other quantity break prices. If you look at the above example pricing records obtained from the endpoint for product: PROD-123

  1. Buy 5 or more of product PROD-123 for $70.00 each
  2. Buy 20 or more of product PROD-123 for $80.00 each. On forced contract, ID: FCONTRACT-1
  3. Buy 1 or more of product PROD-123 for $75.30 each. On contract, ID: CONTRACT-222

If 20 of the product were purchased it would cost $80.00, not $70 since the 2nd price rule is associated to a forced contract. If the 2nd price rule wasn't assigned to a forced contract then the product would cost $70 since the 1st price rule overrides 2nd price rule since it is cheaper.

Customer Accounts

When an one organisation connects to another organisation in the platform, each organisation can assign zero or more customer accounts to each other. The assigned customer account determines the pricing that a retrieving organisation can buy products for off a supplying organisation. It is possible that the supplier organisation may assign multiple customer accounts to a retrieving organisation. This would typically occur if the retrieving organisation had several divisions or contracts in place and wanted clear seperation of purchases. If multiple accounts are assigned then when calling the endpoint the retrieving organisation must explicitly provide the code of the customer account that products should be priced at. If only one customer account is assigned then the customer account code does not need to be specified.

Tips and Recommendations:

  • If possible call the endpoint using the SQUIZZ.com API's native programming language libraries to cut down on the amount of development work needed to retrieve the pricing data. See API Native Programming Libraries.
  • When the price document is being returned from the API, in each of the price records any non-mandatory fields that had the default value set may be omitted from being included in the returned JSON. This cuts down on the amount of redundant JSON data that needs to be downloaded, speeding up retrieval times.
  • Within the returned price document's configs property, the dataFields property will provide a list of all the record properties that can be expected to have data set for each price record. Then if a price field was not included in a record returned from the endpoint, then it can be presumed that its value would have been the default indicated in the table above.
  • If you are saving the retrieved price data to a database, use the list of price fields in the dataFields property to indicate which fields of existing price in your database should be updated. This can be very useful to ensure that not all price fields are being overwritten in your database, allowing some price data to be updated from an external data source, and other price data be left alone.
  • Call the API endpoint to retrieve product data from a supplier first, then use the product data in conjunction with obtaining product pricing data and product stock quantities to match the supplying organisation's products to pricing and stock availability.
  • Note that there are trading token costs to call the endpoint. The supplying organisation may subsidise these costs, based on the data sharing policy assigned to the retrieving organisation. For more details on costs see Trading Tokens and Pricing for more details.

Retrieve Product Stock Quantity Data

The Retrieve Organisation Data endpoint can be called by an organisation to retrieve a list of product available stock quantities from another organisation connected to it on the SQUIZZ.com platform. The endpoint will return a list of stock quantity records in the Stock Quantity Ecommerce Standards Document(ESD) JSON data format that the receiving organisation has been given access to download, based on the Data Sharing Policy that the supplying organisation has assigned to the receiving organisation. The Data Sharing Policy will control which product stock quantities are allowed to be retrieved.

Within the retrieved Stock Quantity JSON document, each stock quantity record is conforms to the Stock Quantity ESD Record format. The following table shows the record fields that this endpoint in the SQUIZZ.com API supports:

Data Type Stock Quantity
Field Name Data Type Mandatory Default Value Description
keyProductID STRING Yes [EMPTY STRING] Unique identifier of the product that the supplier organisation has set, ensuring that only one product has this key identifier across all of a supplier's products. The keyProductID may be the same as the product code, or may be based on an different internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier.
internalID STRING No NULL The unique identifier of the product that the SQUIZZ.com organisation assigned to the supplier's product.
qtyAvailable DECIMAL No 0 The amount of stock available for each product. The quantity available is based on the base sell unit assigned to the product.
qtyOrderable DECIMAL No 0 The amount of stock that is allowed to be ordered for each product. The quantity orderable is based on the base sell unit assigned to the product. If the supplier organisation has given permission for the product to be back ordered then this amount will be set to 1 billion (displayed as 1e9 in scientific notification), otherwise the quantity set will be based on the available quantity, or 0 if the available quantity is less than 0.

HTTP Request Raw Example:

GET https://api.squizz.com/rest/1/org/retrieve_esd/3042EXAMPLEGSESSIONID342?supplier_org_id=1302EXAMPLEORGID&data_type_id=10 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

HTTP Response Example:

Below is an example Stock Quantity Document returned by the API endpoint.

{
 "resultStatus":"1",
 "message":"The product stock quantity data has been successfully obtained.",
 "configs":{"dataFields":"keyProductID,internalID,qtyAvailable"},
 "dataTransferMode": "COMPLETE",
 "version": 1.1,
 "totalDataRecords": 3,
 "dataRecords":
  [
  {
   "keyProductID":"123A",
   "internalID":"12341231ABCAV314123141BCA342",
   "qtyAvailable": 22,
   "qtyOrderable": 22
  },
  {
   "keyProductID":"1234",
   "internalID":"12341231ABCAV3141231412342",
   "qtyAvailable": 16,
   "qtyOrderable": 1e9
  },
  {
   "keyProductID":"7890",
   "internalID":"12341231ABCAV6654631412342",
   "qtyAvailable": -23,
   "qtyOrderable": 0
  }
 ]
}

Tips and Recommendations:

  • If possible call the endpoint using the SQUIZZ.com API's native programming language libraries to cut down on the amount of development work needed to retrieve the pricing data. See API Native Programming Libraries.
  • When the stock quantity document is being returned from the API, in each of the stock quantity records any non-mandatory fields that had the default value set may be omitted from being included in the returned JSON. This cuts down on the amount of redundant JSON data that needs to be downloaded, speeding up retrieval times.
  • Within the returned stock quantity document's configs property, the dataFields property will provide a list of all the record properties that can be expected to have data set for each stock quantity record. Then if a stock quantity field was not included in a record returned from the endpoint, then it can be presumed that its value would have been the default indicated in the table above.
  • If you are saving the retrieved stock quantity data to a database, use the list of stock quantity fields in the dataFields property to indicate which fields of existing stock quantity in your database should be updated. This can be very useful to ensure that not all stock quantity fields are being overwritten in your database, allowing some stock quantity data to be updated from an external data source, and other stock quantity data be left alone.
  • Call the API endpoint to retrieve product data from a supplier first, then use the product data in conjunction with obtaining product pricing data and product stock quantities to match the supplying organisation's products to pricing and stock availability.
  • You may want to call the endpoint to receive product stock quantity data on regular intervals eg. once an hour to have near realtime stock quantity data.
  • Note that there are trading token costs to call the endpoint. The supplying organisation may subsidise these costs, based on the data sharing policy assigned to the retrieving organisation. For more details on costs see Trading Tokens and Pricing for more details.