MENU

Platform API Endpoint: Import Organisation Data

Within the SQUIZZ.com Application Programming Interface (API) it contains an endpoint that allows one organisation using 3rd party software to import and store data in the platform. This data could be products, pricing, or stock availability, taxcodes, customer accounts, and much more. The "Import Organisation Data" endpoint can be used to automate a number of processes, including the sharing of data between different organisations, and regularly keeping organisation data up to date. The data imported into the platform will be hosted on the platforms servers, and then be available to be shared with connected organisations and people, if given permission.
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. Import Taxcodes
  4. Import Price Levels
  5. Import Products
  6. Import Product Price-Level Unit Pricing
  7. Import Product Price-Level Quantity Based Pricing
  8. Import Product Customer Account Pricing
  9. Import Product Alternate Codes
  10. Import Product Stock Quantities
  11. Import Sales Representatives
  12. Import Customer Accounts
  13. Import Supplier Accounts
  14. Import Locations
  15. Import Purchasers
  16. Import Surcharges
  17. Import Payment Types
  18. Import Sell Units

Overview

The endpoint imports different lists of organisation data based on the given data type. The data being imported must be placed into the Body of the HTTP request in the form of a conforming Ecommerce Standards Document JSON string that matches with the data type specified. For example this endpoint can be used to import a list of product records that have been wrapped up within a JSON formatted "Products Ecommerce Standards Document".Before using this endpoint we recommend that you understand what the Ecommerce Standards Documents are and how you can convert business data from your system into the standards. It is highly recommended that any data uploaded using this endpoint be compressed using the GZIP compression algorithm and uploaded in a stream. Note that there are trading token costs to import the organisation data using this API, of which the organisation importing the data must have enough tokens to allow the data to import. See the Trading Tokens and Pricing Help page for data import costs.

Data Import Types

Below is a list of the following types of documents and records that can be imported into the platform, with the data structured in JSON data conforming to the Ecommerce Standards Documents:

HTTP Request

HTTP Method POST
HTTP URL https://api.squizz.com/rest/1/org/import_esd/session_id
Parameters Data Type Mandatory Description
session_id STRING Yes ID of the API session. Place the session ID within the URL
import_type_id INTEGER Yes ID of the data type being imported. Set one of the numbers:
Body JSON Yes Body contains a type of Ecommerce Standards Document with one or more records that has been serialized into a JSON data string.

 

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 imported into the platform against the organsiation.
result_code STRING Status code of trying to import the ESD document data. See the Appendix I for the list of possible result codes.
api_version STRING Version of the API being used to handle the endpoint request.

 

HTTP Response Example:

{"result":"SUCCESS", "api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}

Import Taxcodes

The Import Organisation Data endpoint can be called by an organisation to import a list of taxcodes into the SQUIZZ.com platform. Each taxcode record specifies one kind of tax (such as Goods and Services (GST), Value Added Tax (VAT), Sales Tax, and many others) and the percentage amount that the tax may apply to products being sold or purchased. Taxcodes are required to be imported against an organisation before any product data to ensure that products have the correct taxcode assigned to them. Taxcodes may also be required to be imported when importing invoices from suppliers back into an organisation's own business system. Note that multiple taxcodes may be applied to single order/invoice lines (such as for countries like USA where both federal and state based taxes apply).

The endpoint needs to POST a list of taxcode records in the Taxcode Ecommerce Standards Document(ESD) JSON data format. The endpoint will return an general Ecommerce Standards Document in the JSON data format that indicates if the taxcodes were successfully imported or not. Taxcodes can only be imported by an organisation if it has enough trading tokens to covert the costs of the taxcodes data import.See Trading Tokens and Pricing for more details.

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

Data Type Taxcode
Field Name Data Type Mandatory Default Value Max Length Description
keyTaxcodeID STRING Yes [EMPTY STRING] 50 Unique identifier of the taxcode record that the organisation has set. Ensure that only one taxcode has this key identifier across all of a taxcodes. The keyTaxcodeID may be the same as the  taxcode field, 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.
taxcode STRING No [EMPTY STRING] 50 The human known code of the taxcode This may or may not be unique, but typically each taxcode record will have its own unique code. Eg. GST, VAT, WET, ST
taxcodePercentageRate DECIMAL No 0 14.4 The percentage amount of tax that the taxcode may be used to calculate on top of a price. The percentage is expressed as a whole number, eg. set to 10 to specify 10% tax, set to 12.5 to specify a 12.5% tax rate.
taxcodeLabel STRING No [EMPTY STRING] 80 Label of the taxcode. Allows people to understand what the taxcode is, or the kind of tax being applied. Eg. "Goods and Services", "Federal Sales Tax"
description STRING No [EMPTY STRING] 50 Text that describes what the taxcode is its purpose.

HTTP Request Raw Example:

Below is an example Taxcode Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=1 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "resultStatus":"1",
    "message":"",
    "configs":{"dataFields":"keyTaxcodeID,taxcode,taxcodePercentageRate,taxcodeLabel,description"},
    "dataTransferMode": "COMPLETE",
    "version": 1.3,
    "totalDataRecords": 3,
    "dataRecords":
     [
        {
            "keyTaxcodeID":"1",
            "taxcode": "GST",
            "taxcodePercentageRate": 10,
            "taxcodeLabel": "Goods And Services",
            "description": "Goods and Services 10% Tax"
        },
        {
            "keyTaxcodeID":"TAX2",
            "taxcode": "VAT",
            "taxcodePercentageRate": 17.5,
            "taxcodeLabel": "Value Added Tax",
            "description": "Value Added Tax 17.5% Tax"
        },
        {
            "keyTaxcodeID":"SST",
            "taxcode": "SST",
            "taxcodePercentageRate": 12,
            "taxcodeLabel": "State Sales Tax",
            "description": "State Sales Tax 12% Tax"
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the taxcode data. See API Native Programming Libraries.
  • Typically taxcode data only needs to be imported by organisations at the start of a new financial year, or when goverments change tax laws and regulations.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import. For more details on costs see Trading Tokens and Pricing for more details.

Import Price Levels

The Import Organisation Data endpoint can be called by an organisation to import a list of price levels into the SQUIZZ.com platform. Price levels allow for multiple prices to be set against each product. Customer accounts are then designated to a price level, and this determines the pricing that the customer will see when purchasing products. Price levels allow organisations to sell a product at different prices to certain customers. For example customers who repeatedly buy in bulk may be assigned to a price level that allows them to buy products at a cheaper price than other customers who buy less and are assigned to a more expensive price level. Price levels can be also be used to set prices of products for customers within different regions of a country or international. Price levels are  conditionally required to be imported by an organisation first before any product price-level pricing data is imported.

The endpoint needs to POST a list of price level records in the Price Level Ecommerce Standards Document(ESD) JSON data format. The endpoint will return an general Ecommerce Standards Document in the JSON data format that indicates if the price levels were successfully imported or not. Price Levels can only be imported by an organisation if it has enough trading tokens to covert the costs of the price level data import.See Trading Tokens and Pricing for more details.

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

Data Type Price Level
Field Name Data Type Mandatory Default Value Max Length Description
keyPriceLevelID STRING Yes [EMPTY STRING] 50 Unique identifier of the price level record that the organisation has set. Ensure that only one price level has this key identifier across all of a price levels. The keyPriceLevelID  could be based on an internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier, or otherwise identified by a code created by a person.
label STRING No [EMPTY STRING] 100 Label of the price level. Allows people to understand what the price level is, or the kind of pricing the price level applies to. Eg. "Recommended Retail Price", "Trade Price", "VIP Customers Price"

HTTP Request Raw Example:

Below is an example Price Level Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=2 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "resultStatus":"1",
    "message":"",
    "configs":{"dataFields":"keyPriceLevelID,label"},
    "dataTransferMode": "COMPLETE",
    "version": 1.3,
    "totalDataRecords": 3,
    "dataRecords":
     [
        {
            "keyPriceLevelID":"1",
            "label": "Recommended Retail Price (RRP)"
        },
        {
            "keyPriceLevelID":"PL2",
            "label": "VIP Customer Price"
        },
        {
            "keyTaxcodeID":"3",
            "label": "Trade Business Price"
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the price level data. See API Native Programming Libraries.
  • Typically price level data only needs to be imported by organisations when a new price level is added to their business systems.
  • Many business systems have a fixed number of price levels that don't change, and if that's the case then the price level data would only need to be imported once.
  • Price Levels need to be imported before Customer Account data to ensure Customer Accounts can be assigned to a price level.
  • Price Levels need to be imported before Product Price Level Unit Pricing and product Price Level Quantity Pricing to ensure pricing data can be saved against an existing price level.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import. For more details on costs see Trading Tokens and Pricing for more details.

Import Products

The Import Organisation Data endpoint can be called by an organisation to import a list of products into the SQUIZZ.com platform. Each product may be physical object such as a chair, or a non-physical product such as a ticket to an event. Once imported the organisation can sell these products to other organisations and people on the platform, or use the products to match up inventory being purchased from other supplier organisations.

The endpoint needs to POST a list of product records in the Product Ecommerce Standards Document(ESD) JSON data format. The endpoint will return a general Ecommerce Standards Document in the JSON data format that indicates if the products were successfully imported or not. Products can only be imported by an organisation if it has enough trading tokens to covert the costs of the product data import.See Trading Tokens and Pricing for more details.

Within the imported Product ESD JSON document, each product record is conforms to the Product 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 Max Length Description
keyProductID STRING Yes [EMPTY STRING] 50 Unique identifier of the product record that the organisation has set. Ensure that each product its own key identifier set across all of the products. The keyProductID could be based on an internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier, or otherwise a code created by a person.
productCode STRING No [EMPTY STRING] 50 Code that allows the product to be identified and known by people. 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] 255 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. 
name STRING No [EMPTY STRING] 255 Name of the product. The name typically contains natural words that allow it easily understood by people on what the product is, or does.
description1 STRING No [EMPTY STRING] 65535 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] 65535 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] 65535 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] 65535 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.
keyTaxcodeID STRING No [EMPTY STRING] 50 Key identifier of the taxcode that is assigned to the product. This determines the taxcode assigned to the product and the amount of tax that is applied against the product's prices. Ensure that taxcodes have been imported into the platform first, otherwise the taxcode won't get assigned to the product.
keySellUnitID STRING No [EMPTY STRING] 50 Key identifier of the sell unit that is the default sell unit assigned to the product. The default sell unit indicates which of the sell units assigned to the product to display and quantities to be purchased against. Ensure that sell units have been imported into the platform first, otherwise this sell unit won't get set as the product's default.
stockQuantity DECIMAL No 0 14.4 Amount of stock that is available to be purchased, based on the base sell unit assigned to the product.
stockLowQuantity DECIMAL No 0 14.4 Amount of stock that indicates when the product's stock level can be considered low. If the product's stock quantity is less than or equal to this value and higher than the stockNoneQuantity then the product will be marked as low in stock. This stock amount relates to the base sell unit assigned to the product.
stockNoneQuantity DECIMAL No 0 14.4 Amount of stock that indicates when the product's stock level can be considered out of stock. If the product's stock quantity is less than or equal to this value then the product will be marked as out of stock. This stock amount relates to the base sell unit assigned to the product.
brand STRING No [EMPTY STRING] 50 Name of the brand associated with the product. The brand provides a recognised label that helps people identify the manufacturer or provider of the product.
barcode STRING No [EMPTY STRING] 50 Barcode that appears on the product or its packaging. The barcode may be used to identify or match the product, based on the physical barcode set on its packaging.
barcodeInner STRING No [EMPTY STRING] 50 Code within the barcode that appears on the product or its packaging. The inner barcode may be another barcode that appears on the product's packaging, or be used to identify the product.
productClass STRING No [EMPTY STRING] 50 Text that allows the product to be classified with other products. Multiple products may be set to the same class, based on different ways products may be grouped. 
isPriceTaxInclusive ENUM('Y','N') No 'N' 1 Either 'Y' or 'N', if set to Y - Yes then denotes that all of the product's prices are inclusive of tax amount. The tax amount is determined based on the taxcode assigned to the product. If set to N - No then denotes that no tax amount is included in pricing assign to the product.
condition ENUM('UK' ,'N', 'UE', 'UG', 'UA', 'UP', 'RFS', 'RFM', 'D') No UK 2

Specifies the condition of the product stock being sold. Set to one of the following:

  • UK
    Unkonwn
  • N
    New
  • UE
    Used - In Excellent Condition
  • UG
    Used - In Good condition
  • UA
    Used - In Average condition
  • UP
    Used - In Poor condition
  • RFS
    Rebuilt For Sale
  • RFM
    Rebuilt For
  • D
    Damaged
     
conditionNewDateTime LONG INTEGER No 0 20 Date that the product's was created and considered as new. Date is in the form of a number in milliseconds since the 01-01-1970 12:00am Epoch in UTC time-zone, stored as a long integer.
conditionDateTime LONG INTEGER No 0 20 Date that matched the product's indicated current condition. Date is in the form of a number in milliseconds since the 01-01-1970 12:00am Epoch in UTC time-zone, stored as a long integer.
width DECIMAL No 0 14.4 The width measurement of each unit of the product. Indicates how wide the product's unit is.
height DECIMAL No 0 14.4 The height measurement of each unit of the product. Indicates how tall the product's unit is.
depth DECIMAL No 0 14.4 The depth measurement of each unit of the product. Indicates how deep the product's unit is.
weight DECIMAL No 0 14.4 The weight measurement of each unit of the product. Indicates how much a product's unit weighs.
volume DECIMAL No 0 14.4 The volume measurement of each unit of the product. Indicates how much space the product's unit takes up.
sellUnits ARRAY (SellUnitRecord) No 0 0..N Set an array of 0 or more Sell Unit Records. This allows multiple sell units to be assigned to each product. Each sell unit specifies the quantity that the product can be purchased in as a bundle, such as individual units, packs, boxes, containers... Each sell unit record must have a keySellUnitID set and the baseQuantity as a positive number.
Product Sell Unit Record Fields
keySellUnitID STRING Yes [EMPTY STRING] 50 Key identifier of the sell unit that matches a sell unit previously imported in the Sell Units import. Sell unit indicates which of the sell units is assigned to the product to display and quantities to be purchased against. Ensure that sell units have been imported into the platform first, otherwise this sell unit won't get assigned to the product.
baseQuantity DECIMAL Yes 1 14.4 Specifies the quantity of the product that is made up of the overall base sell unit. If the sell unit is the base sell unit then set to 1.
parentQuantity DECIMAL No 0 14.4 Specifies the quantity of the product that is made up of a parent sell unit assigned to the sell unit.
sellUnitLabel STRING No [EMPTY STRING] 50 Label of the sell unit specific to the product. This label indicates how the product may be bundled up as, such as "Each", "Pack", "Box"
isPricedOffBaseUnit ENUM('Y','N') No 'N' 1 Either 'Y' or 'N'. If "Y" Yes then indicates that the sell unit is to be priced based on pricing data set for the base sell unit that product pricing is assigned to.
keySellUnitParentID STRING No [EMPTY STRING] 50 Set the value KeySellUnitID of another sell unit assigned to the product that may be the parent sell unit. A parent sell unit indicates that this sell units contains a quantity of parent sell units. For example a Pack sell unit may be assigned to a parent sell unit called "Each".

HTTP Request Raw Example:

Below is an example Product Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=3 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3,
    "resultStatus": 1,
    "message":"The product data has been successfully obtained.",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 2,
    "configs":{"dataFields":"keyProductID,productCode,keyTaxcodeID,productSearchCode, barcode,barcodeInner,brand,name,description1, description2,description3,description4,productClass,keySellUnitID,weight, width,height,depth,supplier,stockQuantity,stockNoneQuantity, stockLowQuantity,stockLowQuantity,isPriceTaxInclusive"},
    "dataRecords":
     [
        {
            "keyProductID":"1234",
            "productCode":"PROD-001",
            "keyTaxcodeID":"GST",
            "productSearchCode":"Green-Recycled-Paper-Swisho",
            "barcode":"03423404230",
            "barcodeInner":"234234",
            "brand":"Swisho Paper",
            "name":"Swisho Green Paper Recycled",
            "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",
            "unit":"REAM",
            "weight": 20.1,
            "width": 21,
            "height": 29.7,
            "depth": 10,
            "supplier":"Swisho",
            "stockQuantity": 200,
            "stockNoneQuantity": 0,
            "stockLowQuantity": 10,
            "isPriceTaxInclusive": "N",
            "keySellUnitID": 2,
            "sellUnits":[
                {
                    "keySellUnitID":"2",
                    "sellUnitLabel":"REAM",
                    "baseQuantity": 1
                },
                {
                    "keySellUnitID":"3",
                    "keySellUnitParentID":"2",
                    "sellUnitLabel":"Pack Of 6 Reams",
                    "baseQuantity": 6
                },
                {
                    "keySellUnitID":"4",
                    "keySellUnitParentID":"3",
                    "sellUnitLabel":"Box containing 4 Packs of 6 Reams",
                    "baseQuantity": 24,
                    "parentQuantity": 4
                }
            ]
        },
        {
            "keyProductID":"P2",
            "productCode":"PROD-002",
            "keyTaxcodeID":"GST",
            "productSearchCode":"Blue-Recycled-Paper-Swisho",
            "barcode":"03423404231",
            "barcodeInner":"234235",
            "brand":"Swisho Paper",
            "name":"Swisho Blue Paper Recycled",
            "description1":"Swisho blue coloured paper is the ultimate blue paper.",
            "description2":"Paper built strong and tough by Swisho",
            "description3":"Recommended to be used with none blue inks.",
            "description4":"",
            "productClass":"paper",
            "unit":"Each",
            "weight": 20.1,
            "width": 21,
            "height": 29.7,
            "depth": 10,
            "supplier":"Swisho",
            "stockQuantity": 14,
            "stockNoneQuantity": 2,
            "stockLowQuantity": 20,
            "isPriceTaxInclusive": "N",
            "keySellUnitID": 2,
            "sellUnits":[
                {
                    "keySellUnitID":"2",
                    "sellUnitLabel":"Each",
                    "baseQuantity": 1
                },
                {
                    "keySellUnitID":"3",
                    "keySellUnitParentID":"2",
                    "sellUnitLabel":"Pack Of 4",
                    "baseQuantity": 4
                }
            ]
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the product data. See API Native Programming Libraries.
  • Taxcodes need to be imported before Product data is imported to ensure that a taxcode can be assigned to a product when imported.
  • Sell Units need to be imported before Product data to ensure sell units can be assigned to a product when imported.
  • At least one sell unit must be assigned to a product to allow it to be sold.
  • For each product multiple sell units can be assigned to it, to allow the product to be sold in many different quantities, such as undividual units, packs, containers, train loads, boxes.
  • Sell units can be linked to each other when assigned to each product in a hierarchy. These relationships allow customers to switch between the amount of units they are purchasing for a product.
  • Using sell units may negate the need to create separate products when a product is bundled in different amounts.
  • Product data needs to be imported before pricing data, locations is imported.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import. For more details on costs see Trading Tokens and Pricing for more details.

Import Product Price-Level Unit Pricing

The Import Organisation Data endpoint can be called by an organisation to import a list of price-level unit prices for products into the SQUIZZ.com platform. Each organisation's product may have many prices assigned to it, based on the number of "price levels" imported for each organisation, and the number of sell units assigned to each product. For each price level a pricing record will define the unit price that any customers assigned to the price level will pay to purchase 1 sell unit of the product. Since each product may have many different sell units assigned to it, there can be as many different unit prices assigned to products through this import as there are price-levels and sell units assigned to a product. For example if an organisation has previously imported 5 different price-levels, and for a "tea-towel" product it is assigned to 3 different sell units "Each", "Pack", "Container", then a product can have imported 5x3 = 15 different price-level unit prices. Using price levels an organisation may have cheaper or more expensive unit prices for each product, to sell the product for cheaper to customers on one price-level compared to other customers assigned to more expensive price levels.
Unit prices are used in product search listings on the platform so that customers of an organisation can initially see how much a product costs for them if they had bought a single product of a given sell unit.

The endpoint needs to POST a list of pricing records in the Pricing Ecommerce Standards Document(ESD) JSON data format. The endpoint will return a general Ecommerce Standards Document in the JSON data format that indicates if the pricing records were successfully imported or not. Pricing records can only be imported by an organisation if it has enough trading tokens to covert the costs of the price-evel unit pricing data import.See Trading Tokens and Pricing for more details.

Within the imported Price ESD JSON document, each pricing 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 Pricing
Field Name Data Type Mandatory Default Value Max Length Description
keyProductID STRING Yes [EMPTY STRING] 50 Identifier of the product record that pricing record applies to for the organisation. The value set must match the keyProductID of a product imported preivously through the Products Data Import as listed above.
keyPriceLevelID STRING Yes [EMPTY STRING] 50 Identifier of the price-level record that the pricing record applies to for the organisation. The value set must match the keyPriceLevelID of a price-level imported preivously through the Price Levels Data Import as listed above.
keySellUnitID STRING Yes [EMPTY STRING] 50 Identifier of the sell unit record that the pricing record applies to for the organisation. The value set must match the keySellUnitID of a sell unit imported preivously through the Sell Units Data Import as documented.
price DECIMAL Yes 0 14.4 Monetary amount that the product can be purchased for, based on given price-level and sell unit. The price must be greater than 0 to allow the price record to import.
referenceID STRING No [EMPTY STRING] 50 Contains the ID of any record that the price may reference, such as a promotion, contract, or other related record in an external business system.
referenceType STRING No [EMPTY STRING] 50

Defines the type of record that the price may be referencing. Common types are:

  • C
    Contract
  • CF
    Contract with forced pricing that overrides cheaper prices
  • P
    Promotion
taxRate DECIMAL No [NULL] 14.4 If given specifies that amount of tax that is included in the price as a percentage. The tax amount is referenced against the taxcode assigned to the product. The percentage is expressed as a whole number, eg. 10% tax would have a value set as 10.0000.

HTTP Request Raw Example:

Below is an example Price Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=4 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3
    "resultStatus": 1,
    "message":"",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 5,
    "configs":{"dataFields":"keyProductID,keyPriceLevelID,keySellUnitID,price"},
    "dataRecords":
    [
        {
            "keyProductID":"PROD-123",
            "keyPriceLevelID":"PL-001",
            "keySellUnitID": "EA",
            "price": 10.00
        },
        {
            "keyProductID":"PROD-123",
            "keyPriceLevelID":"PL-001",
            "keySellUnitID": "PACK",
            "price": 40.00
        },
        {
            "keyProductID":"PROD-123",
            "keyPriceLevelID":"PL-002",
            "keySellUnitID": "EA",
            "price": 8.00
        },
        {
            "keyProductID":"PROD-123",
            "keyPriceLevelID":"PL-003",
            "keySellUnitID": "EA",
            "price": 5.00
        },
        {
            "keyProductID":"PROD-456",
            "keyPriceLevelID":"PL-001",
            "keySellUnitID": "EA",
            "price": 22.00
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the pricing data. See API Native Programming Libraries.
  • Price Levels need to be imported before pricing data is imported to ensure that a price record can be assigned to a price-level for a product when imported.
  • Sell Units need to be imported before Product data to ensure sell units can be assigned to a product when imported.
  • Products need to be imported before pricing data is imported to ensure that a price record can be assigned to a product when imported.
  • For each product multiple price-level unit prices can be assigned to it, to allow the product to be sold in many price-levels. Additionally multiple price-level unit prices can be assigned to the same price-level for a product across all the different sell units assigned to the product.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import. For more details on costs see Trading Tokens and Pricing for more details.
  • Only import price-level unit prices for price-levels actively being used or download by customers. Having unused price records will cost more trading tokens for little positive value.
  • Once price-level unit pricing has been imported then customers may be able to download the pricing for their assigned price level through the API's retrieve data endpoint, or in platform. based on the customer account that a customer is assigned to. This allows customers to automate the retrieval of pricing data back into their own systems.
  • Update pricing regularly to ensure that any sales orders created by customers contains the most up to date pricing.
  • Only one quantity break direction can be set across all product quantity prices. For example the Quantity Break Direction can be set to one of the following within the Organisation Settings (make sure this matches the business system where the prices are coming from):
    • Buy Over Quantity For Price X
    • Buy Equal To Or Over Quantity For Price X
    • Buy Under Quantity For Price X
    • Buy Equal to Or Under Quantity For Price X

Import Product Price-Level Quantity Based Pricing

The Import Organisation Data endpoint can be called by an organisation to import a list of price-level quantity prices for products into the SQUIZZ.com platform. Each organisation's product may have many prices assigned to it, based on the number of "price levels" imported for each organisation, and the number of sell units assigned to each product, as well as quantity breaks, also known as volume discounts. Quantity based pricing allows customers to buy a product for a cheaper price when they purchase over/equal to and over/under/equal to or under a specified quantity. This allows customers to receive discounts by purchasing products in greater quantities. The "product price-level quantity based pricing" import allows quantity break pricing to be imported against each product for a specified price-level and sell unit. This allows customers on an assigned price-level to receive certain volume discounts for each product that other customers assigned to other price-levels may not.

For each price level a pricing record will define the quantity based price that any customers assigned to the price level will pay to purchase 1 sell unit of the product. Since each product may have many different sell units assigned to it, there can be as many different quantity based prices assigned to products through this import as there are price-levels and sell units assigned to a product. For example if an organisation has previously imported 5 different price-levels, and for a "tea-towel" product it is assigned to 3 different sell units "Each", "Pack", "Container", and 4 quantity breaks exist for all price-levels, then a product can have imported 5x3x4 = 60 different price-level quantity based prices.

The endpoint needs to POST a list of pricing records in the Pricing Ecommerce Standards Document(ESD) JSON data format. The endpoint will return a general Ecommerce Standards Document in the JSON data format that indicates if the pricing records were successfully imported or not. Pricing records can only be imported by an organisation if it has enough trading tokens to covert the costs of the price-evel unit pricing data import.See Trading Tokens and Pricing for more details.

Within the imported Price ESD JSON document, each pricing 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 Pricing
Field Name Data Type Mandatory Default Value Max Length Description
keyProductID STRING Yes [EMPTY STRING] 50 Identifier of the product record that pricing record applies to for the organisation. The value set must match the keyProductID of a product imported preivously through the Products Data Import as listed above.
keyPriceLevelID STRING Yes [EMPTY STRING] 50 Identifier of the price-level record that the pricing record applies to for the organisation. The value set must match the keyPriceLevelID of a price-level imported preivously through the Price Levels Data Import as listed above.
keySellUnitID STRING Yes [EMPTY STRING] 50 Identifier of the sell unit record that the pricing record applies to for the organisation. The value set must match the keySellUnitID of a sell unit imported preivously through the Sell Units Data Import as documented.
price DECIMAL Yes 0 14.4 Monetary amount that the product can be purchased for, based on given price-level and sell unit. The price must be greater than 0 to allow the price record to import.
quantity DECIMAL Yes 0 14.4 The quantity of the product's sell unit that the price is applicable to. The quantity must be greater than 0 to allow the price record to import.
referenceID STRING No [EMPTY STRING] 50 Contains the ID of any record that the price may reference, such as a promotion, contract, or other related record in an external business system.
referenceType STRING No [EMPTY STRING] 50

Defines the type of record that the price may be referencing. Common types are:

  • C
    Contract
  • CF
    Contract with forced pricing that overrides cheaper prices
  • P
    Promotion
taxRate DECIMAL No [NULL] 14.4 If given specifies that amount of tax that is included in the price as a percentage. The tax is referenced against the taxcode assigned to the product. The percentage is expressed as a whole number, eg. 10% tax would have a value set as 10.0000.

HTTP Request Raw Example:

Below is an example Price Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=4 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3
    "resultStatus": 1,
    "message":"",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 6,
    "configs":{"dataFields":"keyProductID,keyPriceLevelID,keySellUnitID,price,quantity"},
    "dataRecords":
    [
        {
            "keyProductID":"PROD-123",
            "keyPriceLevelID":"PL-001",
            "keySellUnitID": "EA",
            "price": 8.00,
            "quantity": 5.00
        },
        {
            "keyProductID":"PROD-123",
            "keyPriceLevelID":"PL-001",
            "keySellUnitID": "EA",
            "price": 6.00,
            "quantity": 10.00
        },
        {
            "keyProductID":"PROD-123",
            "keyPriceLevelID":"PL-001",
            "keySellUnitID": "EA",
            "price": 4.00,
            "quantity": 20.00
        },
        {
            "keyProductID":"PROD-123",
            "keyPriceLevelID":"PL-001",
            "keySellUnitID": "EA",
            "price": 2.00,
            "quantity": 40.00
        },
        {
            "keyProductID":"PROD-123",
            "keyPriceLevelID":"PL-001",
            "keySellUnitID": "PACK",
            "price": 30.00,
            "quantity": 10.00
        },
        {
            "keyProductID":"PROD-456",
            "keyPriceLevelID":"PL-001",
            "keySellUnitID": "EA",
            "price": 18.00,
            "quantity": 3.00
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the pricing data. See API Native Programming Libraries.
  • Price Levels need to be imported before pricing data is imported to ensure that a price record can be assigned to a price-level for a product when imported.
  • Sell Units need to be imported before pricing data to ensure sell units can be assigned to a product when imported.
  • Products need to be imported before pricing data is imported to ensure that a price record can be assigned to a product when imported.
  • For each product multiple price-level quantity prices can be assigned to it, to allow the product to be sold in many price-levels. Additionally multiple price-level unit prices can be assigned to the same price-level for a product across all the different sell units assigned to the product.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import. For more details on costs see Trading Tokens and Pricing for more details.
  • Only import price-level quantity prices for price-levels actively being used or download by customers. Having unused price records will cost more trading tokens for little positive value.
  • Once price-level quantity pricing has been imported then customers may be able to download the pricing for their assigned price level through the API's retrieve data endpoint, or in platform. based on the customer account that a customer is assigned to. This allows customers to automate the retrieval of pricing data back into their own systems.
  • Update pricing regularly to ensure that any sales orders created by customers contains the most up to date pricing.

Import Product Customer Account Pricing

The Import Organisation Data endpoint can be called by an organisation to import a list of customer account prices for products into the SQUIZZ.com platform. Each organisation's product may have many prices assigned to it, based on the prices that are assigned to specific customers. This allows products to have pricing set for certain customers, such as used for contracts and promotions. This allows customers to buy a product for a cheaper or dearer price of a product for a specified quantity and sell unit. Each customer account price can force its price to be set for a product, known as Forced Contract pricing, regardness if the customer account is assigned to a price-level price that is cheaper then the account price. This is useful for when a customer agrees to purchase products at a specified price over a certain timeframe, regardless if the product becomes cheaper or dearer over time.

For each pricing record it will define the quantity based price that any customers assigned to it will pay to purchase one or more sell units of the product. Since each product may have many different sell units assigned to it, there can be as many different customer account quantity based prices assigned to products through this import. Customer Account Price records can either be assigned to a specific customer account, or be assigned to a "Price Group". Each price group can contain a list of 0 or more customer accounts assigned to it. By using price groups it may reduce the amount of pricing records that need to be imported in this data import, such as when many customer accounts are assigned to the same contract and receive the same pricing.

The endpoint needs to POST a list of pricing records in the Pricing Ecommerce Standards Document(ESD) JSON data format. The endpoint will return a general Ecommerce Standards Document in the JSON data format that indicates if the pricing records were successfully imported or not. Pricing records can only be imported by an organisation if it has enough trading tokens to covert the costs of the price-evel unit pricing data import.See Trading Tokens and Pricing for more details.

Within the imported Price ESD JSON document, each pricing 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 Pricing
Field Name Data Type Mandatory Default Value Max Length Description
keyProductID STRING Yes [EMPTY STRING] 50 Identifier of the product record that pricing record applies to for the organisation. The value set must match the keyProductID of a product imported preivously through the Products Data Import as listed above.
keyAccountID STRING Conditional [EMPTY STRING] 50 Identifier of the customer account record that the pricing record applies to for the organisation. The value set must match the keyCustomerAccountID of a customer account record imported preivously through the Customer Accounts Data Import as listed above. The keyAccountID does not need to be set if the keyPriceGroupID field has been set.
keyPriceGroupID STRING Conditional [EMPTY STRING] 50 Identifier of the price-group record that the pricing record applies to for the organisation. The value set must match the keyPriceGroupID of a price group record that exists within the priceGroups object within the Price document being imported. The keyPriceGroupID does not need to be set if the keyAccountID field has been set.
keySellUnitID STRING Yes [EMPTY STRING] 50 Identifier of the sell unit record that the pricing record applies to for the organisation. The value set must match the keySellUnitID of a sell unit imported preivously through the Sell Units Data Import as documented.
price DECIMAL Yes 0 14.4 Monetary amount that the product can be purchased for, based on given customer account/price group and sell unit. The price must be greater than 0 to allow the price record to import.
quantity DECIMAL Yes 0 14.4 The quantity of the product's sell unit that the price is applicable to. The quantity must be greater than 0 to allow the price record to import.
referenceID STRING No [EMPTY STRING] 50 Contains the ID of any record that the price may reference, such as a promotion, contract, or other related record in an external business system.
referenceType STRING No [EMPTY STRING] 50

Defines the type of record that the price may be referencing. Common types are:

  • C
    Contract
  • CF
    Contract with forced pricing that overrides cheaper prices
  • P
    Promotion
taxRate DECIMAL No [NULL] 14.4 If given specifies that amount of tax that is included in the price as a percentage. The tax is referenced against the taxcode assigned to the product. The percentage is expressed as a whole number, eg. 10% tax would have a value set as 10.0000.

HTTP Request Raw Example:

Below is an example Price Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=7 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "resultStatus":"1",
    "message":"The product customer account pricing data has been successfully obtained.",
    "configs":{"dataFields":"keyProductID,keyAccountID,keyPriceGroupID,price,quantity,keySellUnitID,referenceID,referenceType"},
    "dataTransferMode": "COMPLETE",
    "version": 1.3,
    "totalDataRecords": 7,
    "priceGroups":
    {
        "PRICE-GROUP-1": ["ACC-1","ACC-2","ACC-3","ACC-4"],
        "PRICE-GROUP-2": ["ACC-4","ACC-5","ACC-6","ACC-7"]
    },
    "dataRecords":
    [
        {
            "keyProductID":"PROD-123",
            "keyAccountID":"ACC-123",
            "price": 70.00,
            "quantity": 5,
            "keySellUnitID": "EACH",
            "referenceID": "FORCED-CONTRACT-1",
            "referenceType": "CF"
        },
        {
            "keyProductID":"PROD-123",
            "keyAccountID":"ACC-123",
            "price": 1.00,
            "quantity": 20,
            "keySellUnitID": "EACH",
            "referenceID": "FORCED-CONTRACT-1",
            "referenceType": "CF"
        },
        {
            "keyProductID":"PROD-123",
            "keyAccountID":"ACC-456",
            "price": 7.30,
            "quantity": 1,
            "keySellUnitID": "PACK",
            "referenceID": "CONTRACT-222",
            "referenceType": "C"
        },
        {
            "keyProductID":"PROD-456",
            "keyAccountID":"ACC-456",
            "price": 3.30,
            "keySellUnitID": "EACH"
        },
        {
            "keyProductID":"PROD-456",
            "keyPriceGroupID":"PRICE-GROUP-1",
            "price": 3.30,
            "quantity": 5,
            "keySellUnitID": "EACH"
        },
        {
            "keyProductID":"PROD-456",
            "keyPriceGroupID":"PRICE-GROUP-2",
            "keySellUnitID": "EACH",
            "price": 2.90,
            "quantity": 1,
            "referenceID": "FORCED-CONTRACT-1",
            "referenceType": "CF"
        },
        {
            "keyProductID":"PROD-789",
            "keyPriceGroupID":"PRICE-GROUP-2",
            "keySellUnitID": "EACH",
            "price": 0.255,
            "quantity": 50
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the pricing data. See API Native Programming Libraries.
  • Customer Accounts need to be imported before pricing data is imported to ensure that a price record can be assigned to a customer account when imported.
  • Sell Units need to be imported before pricing data to ensure sell units can be assigned to a product when imported.
  • Products need to be imported before pricing data is imported to ensure that a price record can be assigned to a product when imported.
  • For each product multiple customer account quantity based prices can be assigned to it, to allow the product to be sold at different prices to several different customer accounts. Additionally multiple product prices can be assigned to the same customer account for a product across all the different sell units assigned to the product.
  • Use price-groups instead of assigning individual customer accounts to price records, when multiple accounts receive the same pricing. For example this could occur if multiple customer accounts are assigned to the same contract, promotion, or deal.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import. For more details on costs see Trading Tokens and Pricing for more details.
  • Only import customer account prices for customer accounts actively being used or downloaded by customers. Having unused price records will cost more trading tokens for little positive value.
  • Once customer account pricing has been imported then customers may be able to download the pricing for their account through the API's retrieve data endpoint, or in platform. based on the customer account that a customer is assigned to. This allows customers to automate the retrieval of pricing data back into their own systems.
  • Update pricing regularly to ensure that any sales orders created by customers contains the most up to date pricing.

Import Product Alternate Codes

The Import Organisation Data endpoint can be called by an organisation to import a list of alternate codes that are linked to an organisation's products imported into the SQUIZZ.com platform. Each alternate code can be linked to a product, and denote that the alternate code may be a code assciated to a product of a manufacturer, supplier, customer, industry, standards product, or be linked to a another product. Alternate codes allow a product to have many different codes known by different people and systems.

The endpoint needs to POST a list of alternate code records in the Alternate Code Ecommerce Standards Document(ESD) JSON data format. The endpoint will return an general Ecommerce Standards Document in the JSON data format that indicates if the alternate codes were successfully imported or not. Alternate Codes can only be imported by an organisation if it has enough trading tokens to covert the costs of the alternate code data import.See Trading Tokens and Pricing for more details.

Within the imported Alternate Code ESD JSON document, each alternate code record is conforms to the Alternate Code ESD Record format. The following table shows the record fields that this endpoint in the SQUIZZ.com API supports:

Data Type Alternate Code
Field Name Data Type Mandatory Default Value Max Length Description
keyProductID STRING Yes [EMPTY STRING] 50 Identifier of the product record that the alternate code record applies to for the organisation. The value set must match the keyProductID of a product imported preivously through the Products Data Import as listed above.
alternateCode STRING Yes [EMPTY STRING] 50 The alternate code associated to the product. This code could be a manufacturer's product code, industry product code, old product code, or code associated to a supplier or customer's product.
isSupplierCode ENUM('Y','N') No 'N' 1 Set to either 'Y' - Yes or 'N' - No. If set to Y then denotes that the alternate code is a code associated to a supplier's product.
keySupplierAccountID STRING No [NULL] 50 Identifier of the supplier account record that the alternate code record is linked to for the organisation. This can denote that the alternate code is a supplier's product code. The value set must match the keySupplierAccountID of a supplier account imported preivously through the Supplier Accounts Import.
keyCustomerAccountID STRING No [NULL] 50 Identifier of the customer account record that the alternate code record is linked to for the organisation. This can denote that the alternate code is a customer's product code. The value set must match the keyCustomerAccountID of a customer account imported preivously through the Customer Accounts Import.
isUseCode ENUM('Y','N') No 'N' 1 Set to either 'Y' - Yes, or 'N' - No. If set to Y then it denotes that the alternate code is the code of another product that should be viewed/purchased instead of the product that the alternate code is assigned to.

HTTP Request Raw Example:

Below is an example Alternate Code Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=9 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3,
    "resultStatus": 1,
    "message":"The product alternate code data has been successfully obtained.",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 3,
    "configs":{"dataFields":"keyProductID,alternateCode,isUseCode,isSupplierCode,keySupplierAccountID,keyCustomerAccountID"},
    "dataRecords":
        [
        {
            "keyProductID":"123A",
            "alternateCode":"043432-IND"
        },
        {
            "keyProductID":"123A",
            "alternateCode":"SWISH-1234",
            "isUseCode":"N",
            "isSupplierCode":"Y",
            "keySupplierAccountID":"SUP2"
        },
        {
            "keyProductID":"1234",
            "alternateCode":"SWISH-4567",
            "isUseCode":"Y",
            "isSupplierCode":"N",
            "keyCustomerAccountID":"222"
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the alternate code data. See API Native Programming Libraries.
  • Products need to be imported before Alternate Code data to ensure that the alternate codes can be assigned to an existing product in the platform.
  • Supplier Accounts needs to be imported before to ensure that any alternate codes that reference a supplier account can be assigned to a supplier account already imported into the platform.
  • Customer Accounts needs to be imported before to ensure that any alternate codes that reference a customer account can be assigned to a customer account already imported into the platform.
  • Assign alternate codes to products that contain the supplier's product code and are linked to a supplier account. This will allow the Order Procurement process to automatically find and match the supplier's products to a purchase order being submitted by the organisation.
  • Assign alternate codes to products that contain the customer's product code and are linked to a customer account. This will allow the Invoicing process to automatically find and match the customer's products when an invoice is being sent back to a customer.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import. For more details on costs see Trading Tokens and Pricing for more details.

Import Product Stock Quantities

The Import Organisation Data endpoint can be called by an organisation to import a list of stock quantities available for products imported by an organisation into the SQUIZZ.com platform. This allows the available stock quantities of products to be updated on a regular basis, which may be required to indicate if products are able to be purchased or not. Each of the stock quantities given indicates how much stock is available be purchased for a product's base sell unit.

The endpoint needs to POST a list of stock quantity records in the Stock Quantity Ecommerce Standards Document(ESD) JSON data format. The endpoint will return a general Ecommerce Standards Document in the JSON data format that indicates if the stock quantities were successfully imported or not. In order for stock quantities to be imported the products must first be imported. Stock quantities can only be imported by an organisation if it has enough trading tokens to cover the costs of the stock quantities data import.See Trading Tokens and Pricing for more details.

Within the imported Stock Quantity ESD 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 Product
Field Name Data Type Mandatory Default Value Max Length Description
keyProductID STRING Yes [EMPTY STRING] 50 Key identifier of the product record that the stock quantity is to be updated against. Ensure that the keyProductID matches that of a product previously imported in the Products data import.
qtyAvailable DECIMAL Yes 0 14.4 Quantity of the product's stock's base sell units that is available and stocked.

HTTP Request Raw Example:

Below is an example Product Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=10 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3,
    "resultStatus": 1,
    "message":"The product data has been successfully obtained.",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 2,
    "configs":{"dataFields":"keyProductID,qtyAvailable"},
    "dataRecords":
     [
        {
            "keyProductID":"1234",
            "qtyAvailable": 33.0000
        },
        {
            "keyProductID":"P2",
            "qtyAvailable": -4
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the stock quantity data. See API Native Programming Libraries.
  • Stock quantities need to be imported only after Product data has first been imported data to ensure that stock units can be assigned to a product when imported.
  • Use this Stock Quantities data import to regularly update the available stock quantities for products to customers. The more often the stock quantities are updated the closer an accurate figure is available to customers.
  • Product stock quantities can also be updated using the Products data import, however the Stock Quantities data import is a much more lightweight and faster approach to update stock quantities due to the reduced amount of data needing to be uploaded and processed.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import data. For more details on costs see Trading Tokens and Pricing for more details.

Import Sales Representatives

The Import Organisation Data endpoint can be called by an organisation to import a list of sales representatives into the SQUIZZ.com platform. Each sales representative record indicates a person or other entity that can sell goods and services for the organiation. Sales representatives can be assigned as a default to each customer account, to act as an account manager, as well be linked to one or more people. This allows people connected to the organisation, and a sales representative to view details of its assigned customer account, as well as create sales orders. When sales orders are raised the sales representative who created the sales order may be assigned to it. This can be used by organisations to report how much a sales representative is selling, and may be used to determine bonuses, commissions or other actions for people associated to the sales representative record.

The endpoint needs to POST a list of sales representative records in the Sales Representative Ecommerce Standards Document(ESD) JSON data format. The endpoint will return a general Ecommerce Standards Document in the JSON data format that indicates if the sales representatives were successfully imported or not. Sales Representatives can only be imported by an organisation if it has enough trading tokens to cover the costs of the sales representatives data import.See Trading Tokens and Pricing for more details.

Within the imported Sales Representative ESD JSON document, each sales representative record is conforms to the Sales Representative ESD Record format. The following table shows the record fields that this endpoint in the SQUIZZ.com API supports:

Data Type Sales Representative
Field Name Data Type Mandatory Default Value Max Length Description
keySalesRepID STRING Yes [EMPTY STRING] 50 Unique identifier of the sales representative record that the organisation has set. Ensure that each sales representative  has its own key identifier set across all of the sales representatives. The keySalesRepID could be based on an internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier, or otherwise a code created by a person.
salesRepCode STRING No [EMPTY STRING] 50 Code that allows the sales representative to be identified and known by people. Typically this code is unique to each sales representative that the organisation has.
name STRING No [EMPTY STRING]   Name of either the sales representative's individual person's name, or the name of the organisation or entity that the sales representative consists of.
contact STRING No [EMPTY STRING]   Name of the contact person associated with the sales representative.
isIndividual ENUM('Y','N') No 'Y' 1 Set to either 'Y' - yes, or 'N' - no. If set to 'Y' then denotes that the sales representative is an indidual person. If set to 'N' then the sales representative may be an organisation or other entity consisting of many people.

HTTP Request Raw Example:

Below is an example Sales Representative Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=16 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3,
    "resultStatus": 1,
    "message":"",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 2,
    "configs":{"dataFields":"keySalesRepID,name,salesRepCode,contact,isIndividual"},
    "dataRecords":
        [
        {
            "keySalesRepID":"REP-2",
            "salesRepCode": "JD",
            "contact": "John Doe",
            "isIndividual": "Y"
        },
        {
            "keySalesRepID":"4533",
            "salesRepCode": "AI",
            "name": "Acme Industries",
            "contact": "Kevin Peterson",
            "isIndividual": "N"
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the sales representative data. See API Native Programming Libraries.
  • Sales representative records need to be imported before customer account records to ensure that customer accounts can be assigned to sales representatives.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import data. For more details on costs see Trading Tokens and Pricing for more details.

Import Customer Accounts

The Import Organisation Data endpoint can be called by an organisation to import a list of customer accounts into the SQUIZZ.com platform. Each customer account represents an organisation or person who buys off the organisation as a customer. Each customer accounts defines the payment terms, payment methods, and pricing that the customer is allowed to buy goods and services off the organisation for. A customer account is also known as a "debtor", which is used within accounting business systems to track the money that has been transferred between the customer and the organisation. A customer account may also be known as a "Vendor", "Business Partner" or "Customer", depending on the software an organisation users uses. Each customer account may have a number of records associated to it, including invoices, sales orders, back orders, payments and credits. It may also have sales representatives, conversations and contracts associated to customer account, required when using the Customer Relationship Management (CRM) features of the SQUIZZ.com platform. Once customer accounts are imported into the SQUIZZ.com platform, this can provide a link back to the associated customer account in the organisation's business system, from which sales orders and invoices can be imported against, and queried by customers in realtime using the platform's Account Enquiry feature. Customer Accounts must be imported into the platform to allow an organisation to sell on the platform to one or more customers.

The endpoint needs to POST a list of customer account records in the Customer Account Ecommerce Standards Document(ESD) JSON data format. The endpoint will return a general Ecommerce Standards Document in the JSON data format that indicates if the customer accounts were successfully imported or not. Customer Accounts can only be imported by an organisation if it has enough trading tokens to cover the costs of the customer accounts data import.See Trading Tokens and Pricing for more details.

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

Data Type Customer Accounts
Field Name Data Type Mandatory Default Value Max Length Description
keyCustomerAccountID STRING Yes [EMPTY STRING] 50 Unique identifier of the customer account record that the organisation has set. Ensure that each customer account  has its own key identifier set across all of the customer accounts. The keyCustomerAccountID could be based on an internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier, or otherwise a code created by a person.
customerAccountCode STRING Yes [EMPTY STRING] 100 Code that allows the customer account to be identified and known by people. Typically this code is unique to each customer account that the organisation has.
accountName STRING No [EMPTY STRING] 255 Name of the customer account. Set a name that allows the account to be recognised, such the name of the organisation or person that the customer account is created for.
contactName STRING No [EMPTY STRING] 80 Name of the contact person associated with the customer account.
orgName STRING No [EMPTY STRING] 80 Name of the organisation if the customer account is associated to an organisation.
email STRING No [EMPTY STRING] 80 Email address that can be used to communicate with the account's contact.
accountClass STRING No [EMPTY STRING] 50 Text that allows the customer account to be classified and optionally grouped with other similar accounts. For example: VIP, Trade, Retail, Class A, Restricted.
territory STRING No [EMPTY STRING] 50 The territory or region that the customer account may be located within. The territory may be based on a postal regions, or be uniquely defined by the organisation. For example: East Coast, West Coast, Mainland.
shippingMethod STRING No [EMPTY STRING] 50 Primary method that may be used to ship goods to the customer.
keyPriceLevelID STRING No [NULL] 50 Identifier of the price-level record that the customer account is assigned to. This specifies what price-level the customer account is assigned to and will see pricing for. The value set must match the keyPriceLevelID of a price-level imported preivously through the Price Levels Data Import as listed above.
keySalesRepID STRING No [NULL] 50 Identifier of the sales representative record that the customer account is assigned to. This specifies the default sales representative that is assigned to this account to manage, also known as an account manager. The value set must match the keySalesRepID of a sales representative imported preivously through the Sales Representatives Data Import.
keyPaymentTypeIDs ARRAY(STRING) No [NULL] 0..N List of keyPaymentTypeID identifiers that are used to assign payment types to the customer account. This indicates the allowed ways that the customer's account can be used to pay for goods and services.
keyLocationIDs ARRAY(STRING) No [NULL] 0..N List of keyLocationID identifiers that are used to assign the customer account to multiple locations. This can indicate the locations that the customer's account may be able to order from, or view product stock availability for. The first keyLocationID listed indicates the primary location of the account, and by default will be assigned to any sales orders that are raised against the customer account.
isOnHold ENUM('Y','N') No 'N' 1 Set to either 'Y' - yes, or 'N' - no. If set to 'Y' then denotes that the account may not able to be used (on hold) to create new sales orders and buy products, since certain terms or conditions of the account are no longer met. An account may be placed on hold until invoices or the account's balance has been reduced by the customer making payments or behaves correctly.
onHoldAction ENUM('OFF', 'WARN', 'WARNCC', 'BLOCK') No 'OFF' 6 If isOnHold is set to Y=Yes and the account is on hold then this denotes if new orders are allowed to be created or not. Set to:
  • OFF
    Ignore On Hold state and still allow ordering
  • WARN
    Ignore On Hold state and still allow ordering. Display warning advising account is on hold.
  • WARNCC
    Ignore On Hold state and still allow ordering. Display warning advising account is on hold but only allow new orders to be created and immediately paid with a credit card .
  • BLOCK
    Don't allow new sales orders to be created and display a block message advising the customer that they cannot order.
isOutsideTerms ENUM('Y','N') No 'N' 1 Set to either 'Y' - yes, or 'N' - no. If set to 'Y' then denotes that the accounts payment terms or conditions are no longer met. Such is if outstanding invoices haven't been paid yet.
outTermsAction ENUM('OFF', 'WARN', 'WARNCC', 'BLOCK') No 'OFF' 6 If isOutsideTerms is set to Y=Yes and the account is outside its payment terms then this denotes if new orders are allowed to be created or not when this occurs. Set to:
  • OFF
    Ignore Outside Payment Terms state and still allow ordering
  • WARN
    Ignore Outside Payment Terms state and still allow ordering. Display warning advising account is outside its payment terms.
  • WARNCC
    Ignore Outside Payment Terms state and still allow ordering. Display warning advising account is outside its payment terms but only allow new orders to be created and immediately paid with a credit card .
  • BLOCK
    Don't allow new sales orders to be created and display a block message advising the customer that they cannot order since their account is outside its payment terms.
isOutsideBalance ENUM('Y','N') No 'N' 1 Set to either 'Y' - yes, or 'N' - no. If set to 'Y' then denotes that the account's balance is greater than the allowed limit. This indicates that the customer has exceeded its allowed limit. This could happen if the organisation extends credit to the customer, and the customer purchases more than they are allowed, or are invoiced purchased exceeding the limit.
outCreditAction ENUM('OFF', 'WARN', 'WARNCC', 'BLOCK') No 'OFF' 6 If isOutsidePayment is set to Y=Yes and the account is outside its account balance limit then this denotes if new orders are allowed to be created or not when this occurs. Set to:
  • OFF
    Ignore Outside Balance state and still allow ordering
  • WARN
    Ignore Outside Balance state and still allow ordering. Display warning advising account is outside its balance limit.
  • WARNCC
    Ignore Outside Balance state and still allow ordering. Display warning advising account is outside its balance limit but only allow new orders to be created and immediately paid with a credit card .
  • BLOCK
    Don't allow new sales orders to be created and display a block message advising the customer that they cannot order since their account is outside its balance limit.
balance DECIMAL No 0 14.4 Specifies the monetary amount that the customer owes to the organisation. A positive balance denotes that the customer is owed money by the organisation (In Credit). A negative amount denotes that the customer owes money to the organisation (In Debt).
limit DECIMAL No 0 14.4 Specifies the maximum monetary amount that the customer is allowed spend and buy goods and services off the organisation. A negative amount denotes that the customer is allowed to buy goods and services without paying upfront (Credit). If the account's balance exceeds this limit then the account's balance is outside its balance. Set the balance to show customers the balance of the account at the time the account was last imported.
termsType ENUM('NA', 'GND', 'DOM', 'NDAE', 'DMAE') No 'NA' 4

Specifies the payment terms on how the customer must pay for invoices and make payments against the customer account. Set to one of the following:

  • NA
    Not Applicable. No payment terms set of the account.
  • GND
    Given Number of Days.
    Purchases/invoices must be paid in a specified number of days from the date of sale. Eg. 30 day account.
  • DOM
    Day Of the Month.
    Purchases/invoices must be paid on a specified day of the month.
  • NDAE
    Number of Days After the End of the month.
    Purchases/invoices must be paid after a specified number of days after the month (or number of months) that the purchase/invoice was raised in.
  • DMAE
    Day of the Month After the End of the month.
    Purchases/invoices must be paid on specified date after the month (or number of months) that the purchase/invoice was raised in.
termsDescription STRING No [EMPTY STRING] 50 Describes the payment terms and conditions that advise when a customer must make payments for sales/invoices raised against the account.

HTTP Request Raw Example:

Below is an example Customer Accounts Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=17 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3,
    "resultStatus": 1,
    "message":"",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 3,
    "configs":{"dataFields":"keyCustomerAccountID,keyPriceLevelID,customerAccountCode,accountName,
contactName,orgName,authorityNumbers,authorityNumberLabels,authorityNumberTypes,
email,accountClass,paymentTypes,territory,discount,shippingMethod,isOnHold,isOutsideBalance,
isOutsideTerms,onHoldAction,outTermsAction,outCreditAction,balance,limit,
termsType,termsDescription"},
    "dataRecords":
        [
        {
            "keyCustomerAccountID":"15C1",
            "keyPriceLevelID":"PL001",
            "customerAccountCode":"CUSTOMER001"
        },
        {
            "keyCustomerAccountID":"222",
            "keyPriceLevelID":"PL004",
            "customerAccountCode":"CUST004",
            "accountName":"John Smith",
            "contactName":"John Smith",
            "orgName":"",
            "authorityNumbers":["2342342334","3432424424243"],
            "authorityNumberLabels":["ABN", "ACN"],
            "authorityNumberTypes":[1,2],
            "email":"js@esdstandards.somewhere",
            "accountClass":"primary",
            "paymentTypes":"CC",
            "territory":"Melb Rural",
            "discount":10,
            "shippingMethod":"Truck",
            "isOnHold":"N",
            "isOutsideBalance":"N",
            "isOutsideTerms":"N",
            "onHoldAction":"OFF",
            "outTermsAction":"OFF",
            "outCreditAction":"OFF",
            "balance":1000.00,
            "limit":0,
            "termsType":"GND",
            "termsDescription":"Pay before 14 days",
            "keyLocationIDs":[]
        },
        {
            "keyCustomerAccountID":"10",
            "keyPriceLevelID":"PL001",
            "customerAccountCode":"CUSTOMER002",
            "accountName":"ESD Industries",
            "contactName":"Joey Joe Joe",
            "orgName":"ESD Industries",
            "authorityNumber":"1234567890",
            "authorityNumberLabel":"ABN",
            "email":"esd@esdstandards.somewhere",
            "accountClass":"secondary",
            "paymentTypes":"AC,CC,DD",
            "territory":"Melb Metro",
            "discount":0,
            "shippingMethod":"",
            "isOnHold":"N",
            "isOutsideBalance":"Y",
            "isOutsideTerms":"N",
            "onHoldAction":"BLOCK",
            "outTermsAction":"WARN",
            "outCreditAction":"WARNCC",
            "balance":-2000.00,
            "limit":1000,
            "termsType":"DOM",
            "termsDescription":"Pay on the 15th day of the month",
            "keyLocationIDs":["LOC1","LOC3","RURA"]
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the sales representative data. See API Native Programming Libraries.
  • Sales Representative records may need to be imported before customer account records to ensure that customer accounts can be assigned to sales representatives, if sales representatives are required to be used.
  • Price Level records need to be imported before customer account records to ensure that customer accounts can be assigned to their price levels, and thus be assigned to product pricing.
  • Location records may need to be imported before customer account records to ensure that customer accounts can be assigned to locations. This is only required if sales orders created against the customer account must have a location assigned to the order.
  • The first keyLocationID in the locations set for each customer account record will be denoted as the default, primary location assigned to the customer account. This primary location will be assigned to sales orders created against the customer account, to denote the location where its products may need to be picked/packed or shipped from.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import data. For more details on costs see Trading Tokens and Pricing for more details.

Import Supplier Accounts

The Import Organisation Data endpoint can be called by an organisation to import a list of supplier accounts into the SQUIZZ.com platform. Each supplier account represents an organisation or person who the organisation purchases goods and services from. Each supplier accounts defines the payment terms, payment methods, and pricing that the supplier is allowed to buy goods and services off the organisation for. A supplier account is also known as a "creditor", which is used within accounting business systems to track the money that has been transferred between the organisation and its supplier. A supplier account may also be known as a "Business Partner" or "Supplier", depending on the software an organisation uses. Each supplier account may have a number of records associated to it, including invoices, purchase orders, payments and credits. It may also have purchasers associated to supplier account to denote which people are allowed to make purchases against the supplier. Once supplier accounts are imported into the SQUIZZ.com platform, this can provide a link back to the associated supplier account in the organisation's business system, from which purchase orders and invoices can be imported against, and queried by purchasers in realtime using the platform's Order procurement feature. Supplier Accounts must be imported into the platform to allow an organisation to buy on the platform with one or more suppliers.

The endpoint needs to POST a list of supplier account records in the Supplier Account Ecommerce Standards Document(ESD) JSON data format. The endpoint will return a general Ecommerce Standards Document in the JSON data format that indicates if the supplier accounts were successfully imported or not. Supplier Accounts can only be imported by an organisation if it has enough trading tokens to cover the costs of the supplier accounts data import.See Trading Tokens and Pricing for more details.

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

Data Type Supplier Accounts
Field Name Data Type Mandatory Default Value Max Length Description
keySupplierAccountID STRING Yes [EMPTY STRING] 50 Unique identifier of the supplier account record that the organisation has set. Ensure that each supplier account  has its own key identifier set across all of the supplier accounts. The keySupplierAccountID could be based on an internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier, or otherwise a code created by a person.
supplierAccountCode STRING Yes [EMPTY STRING] 100 Code that allows the supplier account to be identified and known by people. Typically this code is unique to each supplier account that the organisation has.
accountName STRING No [EMPTY STRING] 255 Name of the supplier account. Set a name that allows the account to be recognised, such the name of the organisation or person that the supplier account is created for.
contactName STRING No [EMPTY STRING] 80 Name of the contact person associated with the supplier account.
orgName STRING No [EMPTY STRING] 80 Name of the organisation if the supplier account is associated to an organisation.
email STRING No [EMPTY STRING] 80 Email address that can be used to communicate with the account's contact.
accountClass STRING No [EMPTY STRING] 50 Text that allows the supplier account to be classified and optionally grouped with other similar accounts. For example: VIP, Trade, Retail, Class A, Restricted.
territory STRING No [EMPTY STRING] 50 The territory or region that the supplier account may be located within. The territory may be based on a postal regions, or be uniquely defined by the organisation. For example: East Coast, West Coast, Mainland.
shippingMethod STRING No [EMPTY STRING] 50 Primary method that may be used to ship goods to the supplier.
keyPriceLevelID STRING No [NULL] 50 Identifier of the price-level record that the supplier account is assigned to. This specifies what price-level the supplier account is assigned to and will see pricing for. The value set must match the keyPriceLevelID of a price-level imported preivously through the Price Levels Data Import as listed above.
keyPurchaserID STRING No [NULL] 50 Identifier of the purchaser record that the supplier account is assigned to. This specifies the default purchaser that is assigned to this account to manage, also known as an purchasing manager. The value set must match the keyPurchaserID of a purchaser imported preivously through the Purchaser Data Import.
isOnHold ENUM('Y','N') No 'N' 1 Set to either 'Y' - yes, or 'N' - no. If set to 'Y' then denotes that the account may not able to be used (on hold) to raise new purchase orders and buy products of its supplier, since certain terms or conditions of the account are no longer met. An account may be placed on hold until invoices or the account's balance has been reduced by making payment to the supplier, or otherwise the supplier is no longer valid or actively trading.
isOutsideTerms ENUM('Y','N') No 'N' 1 Set to either 'Y' - yes, or 'N' - no. If set to 'Y' then denotes that the accounts payment terms or conditions are no longer met. Such is if outstanding invoices haven't been paid yet to the supplier.
isOutsideBalance ENUM('Y','N') No 'N' 1 Set to either 'Y' - yes, or 'N' - no. If set to 'Y' then denotes that the account's balance is greater than the allowed limit. This may have exceeded the supplier's allowed limit or the organisation's own limit. This could happen if the supplier extends credit to the organisation, and the organisation purchases more than they are allowed, or are invoiced purchased exceeding the limit. It could also mean that the organisation has exceeded its own budget and spending against the supplier.
balance DECIMAL No 0 14.4 Specifies the monetary amount that the organisation owes to the  supplier. A positive balance denotes that the organisation is owed money by the supplier (In Credit). A negative amount denotes that the organisation owes money to the supplier (In Debt).
limit DECIMAL No 0 14.4 Specifies the maximum monetary amount that the organisation is allowed spend and buy goods and services off the supplier. A negative amount denotes that the organisation is allowed to buy goods and services without paying upfront (Credit). If the account's balance exceeds this limit then the account's balance is outside its balance. Set it to show the balance of the account at the time the account was last imported.
termsType ENUM('NA', 'GND', 'DOM', 'NDAE', 'DMAE') No 'NA' 4

Specifies the payment terms on how the organisation must pay for invoices and make payments against the supplier. Set to one of the following:

  • NA
    Not Applicable. No payment terms set of the account.
  • GND
    Given Number of Days.
    Purchases/invoices must be paid in a specified number of days from the date of sale. Eg. 30 day account.
  • DOM
    Day Of the Month.
    Purchases/invoices must be paid on a specified day of the month.
  • NDAE
    Number of Days After the End of the month.
    Purchases/invoices must be paid after a specified number of days after the month (or number of months) that the purchase/invoice was raised in.
  • DMAE
    Day of the Month After the End of the month.
    Purchases/invoices must be paid on specified date after the month (or number of months) that the purchase/invoice was raised in.
termsDescription STRING No [EMPTY STRING] 50 Describes the payment terms and conditions that advise when a supplier must make payments for sales/invoices raised against the account.

HTTP Request Raw Example:

Below is an example Supplier Accounts Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=18 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3,
    "resultStatus": 1,
    "message":"The supplier account data has been successfully obtained.",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 3,
    "configs":{"dataFields":"keySupplierAccountID,keyPriceLevelID,supplierAccountCode,accountName,
contactName,orgName,authorityNumbers,authorityNumberLabels,authorityNumberTypes,email,
accountClass,paymentTypes,territory,shippingMethod,isOnHold,isOutsideBalance,
isOutsideTerms,balance,limit,termsType,termsDescription,termsValue1,termsValue2"},
    "dataRecords":
        [
        {
            "keySupplierAccountID":"SUP1",
            "keyPriceLevelID":"PL001",
            "supplierAccountCode":"SUP001"
        },
        {
            "keySupplierAccountID":"SUP2",
            "keyPriceLevelID":"PL004",
            "supplierAccountCode":"SUPL004",
            "accountName":"Suppliers Inc.",
            "contactName":"John Smith",
            "orgName":"Suppliers Inc.",
            "authorityNumbers":["2342342334","3432424424243"],
            "authorityNumberLabels":["ABN", "ACN"],
            "authorityNumberTypes":[1,2],
            "email":"js@esdstandards.somewhere",
            "accountClass":"primary",
            "paymentTypes":"CC",
            "territory":"Melb Rural",
            "shippingMethod":"Truck",
            "isOnHold":"N",
            "isOutsideBalance":"N",
            "isOutsideTerms":"N",
            "balance":1000.00,
            "limit":0,
            "termsType":"GND",
            "termsDescription":"Pay before 14 days",
            "termsValue1":"14",
            "termsValue2":""
        },
        {
            "keySupplierAccountID":"SUP3",
            "keyPriceLevelID":"PL001",
            "supplierAccountCode":"SUP003",
            "accountName":"ESD Industries",
            "contactName":"Joey Joe Joe",
            "orgName":"ESD Industries",
            "authorityNumber":"1234567890",
            "authorityNumberLabel":"ABN",
            "email":"esd@esdstandards.somewhere",
            "accountClass":"secondary",
            "paymentTypes":"AC,CC,DD",
            "territory":"Melb Metro",
            "discount":0,
            "shippingMethod":"",
            "isOnHold":"N",
            "isOutsideBalance":"Y",
            "isOutsideTerms":"N",
            "balance":-2000.00,
            "limit":1000,
            "termsType":"DOM",
            "termsDescription":"Pay on the 15th day of the month",
            "termsValue1":"15",
            "termsValue2":""
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the sales representative data. See API Native Programming Libraries.
  • Purchaser records may need to be imported before supplier account records to ensure that supplier accounts can be assigned to purchasers, if purchasers are required to be used.
  • Assign people (employees, people who purchaser) to Purchaser records to allow them to procure and create purchase orders against the supplier accounts, as well as approve these orders being procured against supplier organisations.
  • Price Level records will need to be imported before supplier account records to price levels to be assigned to the supplier accounts. A price level may specify where its pricing was determined based on cost of purchasing from a supplier.
  • Supplier accounts must be imported to be able to use the Order Procurement processes in the platform to allow the organisation's purchase orders to be sent to the connected supplier organisation and turned turned into the supplier's sales orders.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import data. For more details on costs see Trading Tokens and Pricing for more details.

Import Locations

The Import Organisation Data endpoint can be called by an organisation to import a list of locations into the SQUIZZ.com platform. Each location can represent a physical geographic location such as a store, warehouse, or site at a specified address. Locations may also represent the internal area of building, or a theoretical non-physical location. Each location may have any number of products assigned to it, with each product indicating how much of it is in stock at the location. This is typically used to indicate stock availability at a store, warehouse, building or site. Locations can be assigned to customer accounts, allowing customers to order products from selected locations. Locations can be assigned to sales orders and derived invoices, to indicate where product stock needs to be picked, packed and delivered from. A location can be set at the sales order level, or at the line level allowing individual products to be shipped from multiple locations.

The endpoint needs to POST a list of location records in the Location Ecommerce Standards Document(ESD) JSON data format. The endpoint will return a general Ecommerce Standards Document in the JSON data format that indicates if the locations were successfully imported or not. Locations can only be imported by an organisation if it has enough trading tokens to covert the costs of the location data import.See Trading Tokens and Pricing for more details.

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

Data Type Location
Field Name Data Type Mandatory Default Value Max Length Description
keyLocationID STRING Yes [EMPTY STRING] 50 Unique identifier of the location record that the organisation has set. Ensure that each location its own key identifier set across all of the locations. The keyLocationID could be based on an internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier, or otherwise a code created by a person.
locationCode STRING No [EMPTY STRING] 50 Code that allows the location to be identified and known by people. Typically this code is unique to each location that the organisation contains. The location code may also be known as a warehouse code, warehouse number or warehouse code in other systems.
locationName STRING No [EMPTY STRING] 50 Name of the location. The name allows the location to be easily identified by humans. A location could be named based on its position in the world, such as a street address, suburb, state or country. It could be also named based on what is stored at the location, or the purpose of the location.
isGeographic ENUM('Y','N') No 'N' 1 Either 'Y' or 'N', if set to Y - Yes then denotes that the location physically exists geographically on the Earth. If set to N - No then denotes that the location is non-physical/virtual and has no geographic position.
isActive ENUM('Y','N') No 'Y' 1 Either 'Y' or 'N', if set to Y - Yes then denotes that the location is actively being used for ordering or other processes.
latitude DECIMAL No 0 14.6 The latitude geographic coordinate of the location that allows the location to be found on a map.
longitude DECIMAL No 0 14.6 The longitude geographic coordinate of the location that allows the location to be found on a map.
address1 STRING No [EMPTY STRING] 90 First address field of the location. Typically stores the unit number/apartment number/street number.
address2 STRING No [EMPTY STRING] 90 2nd address field of the location. Typically stores street name.
address3 STRING No [EMPTY STRING] 90 3rd address field of the location. Typically stores the suburb, town or city name of the location.
region STRING No [EMPTY STRING] 70

Name of the region, state or province of the country where the location exists.

country STRING No [EMPTY STRING] 70 Name of the country where the location exists.
postcode STRING No [EMPTY STRING] 30 Set the post code or zipcode of the location's address, associated to the region, state, province.
contact STRING No [EMPTY STRING] 50 Name of the person who is the primary contact at the location.
phone STRING No [EMPTY STRING] 45 Primary phone number that be used to call the location. It's recommended setting a phone number that is internationally or country callable.
fax STRING No [EMPTY STRING] 45 Fax number that be used to send faxes to the location, if fax exists at the location.
productStock ARRAY (StockQuantityRecord) No 0 0..N Set an array of 0 or more Stock Quantity Records. This allows multiple products to be assigned to each location. Each stock quantity can specify the different quantities of product that are record against the location.
Product Sell Unit Record Fields
keyProductID STRING Yes [EMPTY STRING] 50 Key identifier of the product that matches a product previously imported in the Products import. Ensure that products have been imported into the platform first, otherwise products and stock quantities recorded against each won't get assigned to the locations.
qtyAvailable DECIMAL Yes 0 14.4 Specifies the quantity of the product's base sell unit that is stocked and available at the location.
qtyBackordered DECIMAL No 0 14.4 Specifies the quantity of the product's base sell unit that is not available at the location and has been back ordered, ordered from a supplier or other location.
qtyConsigned DECIMAL No 0 14.4 Specifies the quantity of the product's base sell unit that is consigned, that being located at a different location. Such as stock used for demos or product testing.
qtyOnHand DECIMAL No 0 14.4 Specifies the quantity of the product's base sell unit that is stocked and on hand within the location.
qtyOrdered DECIMAL No 0 14.4 Specifies the quantity of the product's base sell unit that has been ordered against the location but not yet picked or delivered.
qtyReserved DECIMAL No 0 14.4 Specifies the quantity of the product's base sell unit that has been reserved against the location and is not available to be ordered, picked, packed or shipped to other customers.

HTTP Request Raw Example:

Below is an example Location Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=23 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3,
    "resultStatus": 1,
    "message":"",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 3,
    "configs":{
        "dataFieldsLocation":"keyLocationID,locationCode,locationName,address1,address2,address3,region,
country,postcode,contact,phone,fax,isActive,isGeographic,latitude,longitude",
        "dataFieldsLocationStock":"keyProductID,qtyAvailable,qtyOnHand,qtyOrdered,qtyBackordered,qtyReserved,qtyConsigned"
    },
    "dataRecords":
    [
        {
            "keyLocationID":"111",
            "locationCode":"LOC-111",
            "locationName":"Local Store"
        },
        {
            "keyLocationID":"123",
            "locationCode":"LOC-123",
            "locationName":"Head Office",
            "address1":"234",
            "address2":"Bourke Street",
            "address3":"Melbourne",
            "region":"Victoria",
            "country":"Australia",
            "postcode":"3000",
            "contact":"John Doe",
            "phone":"+614001112222",
            "fax":"+614002223333",
            "email":"headoffice@example.com",
            "isActive":"Y",
            "isGeographic":"Y",
            "latitude":45.123,
            "longitude":-72.123,
            "website":"www.example.com",
            "locationType":"OFFICE",
            "productStock":[]
        },
        {
            "keyLocationID":"456",
            "locationCode":"LCT-456",
            "locationName":"Warehouse",
            "address1":"237",
            "address2":"Bourke Street",
            "address3":"Melbourne",
            "region":"Victoria",
            "country":"Australia",
            "postcode":"3000",
            "contact":"Max Smith",
            "phone":"+614003334444",
            "fax":"+614005556666",
            "email":"warehouse@example.com",
            "isActive":"Y",
            "isGeographic":"Y",
            "latitude":45.423,
            "longitude":-72.823,
            "website":"www.example.com",
            "locationType":"WAREHOUSE",
            "productStock":
            [
                {
                    "keyProductID":"ABC",
                    "qtyAvailable":432
                },
                {
                    "keyProductID":"DEF",
                    "qtyAvailable":0,
                    "qtyOnHand":0,
                    "qtyOrdered":5,
                    "qtyBackordered":10,
                    "qtyReserved":11,
                    "qtyConsigned":3
                }
            ]
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the location data. See API Native Programming Libraries.
  • Products need to be imported before any location data is imported to ensure that any product stock quantities can be assigned to locations when imported.
  • Locations need to be imported before customer account data to allow customer accounts to be assigned to locations.
  • Set up Sales Order rules within the Admin section of an organsiation's profile to allow different order data to dictate the location that is assigned to a sales order, such as checking the delivery suburb, state or country to determine the most appropriate location to ship ordered products from.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import. For more details on costs see Trading Tokens and Pricing for more details.

Import Purchasers

The Import Organisation Data endpoint can be called by an organisation to import a list of purchasers into the SQUIZZ.com platform. Each purchaser record indicates a person or other entity that can buy goods and services for the organiation. Purchasers can be assigned as a default to each supplier account, to act as an purchaser manager, as well be linked to one or more people. This allows people connected to the organisation, and purchasers to view details of its assigned supplier account, as well as create purchase orders. When purchase orders are raised the purchaser who created the purchaser order may be assigned to it. This can be used by organisations to report how much a purchaser is buying, and may be used to determine budgets or other actions for people associated to the purchaser record. Purchaser records must be imported and assigned against supplier accounts to allow purchasing people within the organisation to use the Order Procurement process to raise orders against supplier organisation(s).

The endpoint needs to POST a list of sales representative records in the Purchaser Ecommerce Standards Document(ESD) JSON data format. The endpoint will return a general Ecommerce Standards Document in the JSON data format that indicates if the purchasers were successfully imported or not. Purchasers can only be imported by an organisation if it has enough trading tokens to cover the costs of the purchaser data import.See Trading Tokens and Pricing for more details.

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

Data Type Purchaser
Field Name Data Type Mandatory Default Value Max Length Description
keyPurchaserID STRING Yes [EMPTY STRING] 50 Unique identifier of the purchaser record that the organisation has set. Ensure that each purchaser  has its own key identifier set across all of the purchaser. The keyPurchaserID could be based on an internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier, or otherwise a code created by a person.
purchaserCode STRING No [EMPTY STRING] 100 Code that allows the purchaser to be identified and known by people. Typically this code is unique to each purchaser that the organisation has.
name STRING No [EMPTY STRING] 100 Name of either the purchaser's individual person's name, or the name of the organisation or entity that the purchaser consists of.
contact STRING No [EMPTY STRING] 50 Name of the contact person associated with the purchaser.
isIndividual ENUM('Y','N') No 'Y' 1 Set to either 'Y' - yes, or 'N' - no. If set to 'Y' then denotes that the purchaser is an indidual person. If set to 'N' then the purchaser may be an organisation or other entity consisting of many people.

HTTP Request Raw Example:

Below is an example Purchaser Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=25 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3,
    "resultStatus": 1,
    "message":"",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 3,
    "configs":{"dataFields":"keyPurchaserID,purchaserCode,contact,isIndividual"},
    "dataRecords":
        [
        {
            "keyPurchaserID":"PUR-1"
        },
        {
            "keyPurchaserID":"PUR-2",
            "purchaserCode": "JD",
            "contact": "John Doe",
            "isIndividual": "Y"
        },
        {
            "keyPurchaserID":"4533",
            "purchaserCode": "AI",
            "name": "Acme Industries",
            "contact": "Kevin Peterson",
            "isIndividual": "N"
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the purchaser data. See API Native Programming Libraries.
  • Purchaser records need to be imported before supplier account records to ensure that supplier accounts can be assigned to purchasers.
  • Once Purchaser records have been imported, multiple people connected to the organisation can be assigned to each Purchaser record. This allows multiple people to manage or purchase for one or more supplier accounts.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import data. For more details on costs see Trading Tokens and Pricing for more details.

Import Surcharges

The Import Organisation Data endpoint can be called by an organisation to import a list of surcharges into the SQUIZZ.com platform. Each surcharge defines an extra charge that may be applied to sales orders and invoices, based on certain rules being met by the customer when buying products. For example an organisation may define a "Credit Card" surcharge that gets applied when a customer buys products off the organisation and pays for the order with a credit card. Another example is that an organisation may define a "Freight" surcharge that gets calculated at different prices depending on where a customer wants ordered goods to be delivered to. Once surcharges are imported by an organisation into the platform they can be then be set within sales order rules to control when they should be applied to sales orders based on specified conditions being met. Additionally surcharges can be applied to invoice payments being made to cover costs for credit card payments.

The endpoint needs to POST a list of surcharge records in the Surcharge Ecommerce Standards Document(ESD) JSON data format. The endpoint will return an general Ecommerce Standards Document in the JSON data format that indicates if the surcharges were successfully imported or not. Surcharges can only be imported by an organisation if it has enough trading tokens to covert the costs of the surcharge data import.See Trading Tokens and Pricing for more details.

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

Data Type Surcharge
Field Name Data Type Mandatory Default Value Max Length Description
keySurchargeID STRING Yes [EMPTY STRING] 50 Unique identifier of the surcharge record that the organisation has set. Ensure that each surcharge has this unique key identifier across all of a surcharges. The keySurchargeID  could be based on an internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier, or otherwise identified by a code created by a person.
surchargeCode STRING No [EMPTY STRING] 50 The human known code of the surcharge This may or may not be unique, but typically each surcharge record will have its own unique code.
surchargeLabel STRING No [EMPTY STRING] 50 Label of the surcharge. Allows people to understand what the surcharge is, or the kind of surcharge is represented. Eg. "Freight Fee", "Credit Card Fee", "Minimum Order Fee", "Fast Freight Fee"
description STRING No [EMPTY STRING] 100 The description of the surcharge that explains what the surcharge, how it is applied, or any conditions.
surchargeType ENUM('FREIGHT', 'CREDITCARD', 'MINORDER','OTHER') No 'OTHER' 10

Specifies the type of surcharge being imported. Set to either:

  • FREIGHT
    Surcharge is related to the cost of freight. Such as the cost to process or deliver ordered goods.
  • CREDITCARD
    Surcharge covers a costs of making a payment with a credit card or other payment method.
  • MINORDER
    Surcharge covers a fee that is applied if the order's total is less than a required minimum total. This surcharge may cover processing costs for orders of low value or size.
  • OTHER
    The surcharge type is not specified.

HTTP Request Raw Example:

Below is an example Surcharge Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=26 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3,
    "resultStatus": 1,
    "message":"",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 3,
    "configs":{"dataFields":"keySurchargeID,surchargeCode,surchargeLabel,description,surchargeType"},
    "dataRecords":
        [
        {
            "keySurchargeID":"456",
            "surchargeCode": "WEB_FREIGHT",
            "surchargeLabel":"Web Order Freight",
            "description": "Costs to deliver orders created through the website.",
            "surchargeType": "FREIGHT"
        },
        {
            "keySurchargeID":"765",
            "surchargeCode": "WEB_CC_SURCHARGE",
            "surchargeLabel": "Web Credit Card Surcharge",
            "description": "Transaction cost for payment made by credit card.",
            "surchargeType": "CREDITCARD"
        },
        {
            "keySurchargeID":"6765",
            "surchargeCode": "WEB_MIN_ORDER",
            "surchargeLabel": "Web Minimum Order Surcharge",
            "description": "Cost to handle orders when an order's total price is under the allowed minimum.",
            "surchargeType": "MINORDER"
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the payment type data. See API Native Programming Libraries.
  • Typically surcharge data only needs to be imported by organisations when a new type of surcharge needs to be applied by an organisation.
  • Surcharges need to be imported before any Sales Order Rules can be set up that apply a surcharge.
  • Surcharges need to be imported before any invoice credit card payments can be set up where a credit card surcharge needs to be applied.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import. For more details on costs see Trading Tokens and Pricing for more details.

Import Payment Types

The Import Organisation Data endpoint can be called by an organisation to import a list of payment types into the SQUIZZ.com platform. Each payment type defines a way that a customer can pay for goods and services. Many payment types can be assigned to each customer account, and when a person needs to pay for either a sales order or invoice linked to a customer account in the platform, the payment options available to the person will be based on the payment types assigned to the account. For example customer accounts may be assigned to a payment type called "On Account", that specifies that the customer pays for orders after an agreed period of time. Another payment type called "Credit Card" could be created that allows customers to pay for sales orders with a credit card at the time of the sales order is being raised. Payment Types are required to be imported by an organisation first before any customer account data is imported.

The endpoint needs to POST a list of payment records in the Payment Type Ecommerce Standards Document(ESD) JSON data format. The endpoint will return an general Ecommerce Standards Document in the JSON data format that indicates if the payment  types were successfully imported or not. Payment Types can only be imported by an organisation if it has enough trading tokens to covert the costs of the payment type data import.See Trading Tokens and Pricing for more details.

Within the imported Payment Type ESD JSON document, each payment type record is conforms to the Payment Type ESD Record format. The following table shows the record fields that this endpoint in the SQUIZZ.com API supports:

Data Type Payment Type
Field Name Data Type Mandatory Default Value Max Length Description
keyPaymentTypeID STRING Yes [EMPTY STRING] 50 Unique identifier of the payment type record that the organisation has set. Ensure that each payment type has this unique key identifier across all of a payment types. The keyPaymentTypeID  could be based on an internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier, or otherwise identified by a code created by a person.
paymentTypeCode STRING No [EMPTY STRING] 50 The human known code of the payment type This may or may not be unique, but typically each payment type record will have its own unique code.
paymentTypeLabel STRING No [EMPTY STRING] 50 Label of the payment type. Allows people to understand what the payment type is, or the kind of payment method the payment type represents. Eg. "On Account", "Credit Card", "Direct Deposit", "Pay Pal", "Running Quote"
description STRING No [EMPTY STRING] 100 The description of the payment type that explains what the payment type is or how it allows for payment.
paymentMethod ENUM('UNPAID', 'CREDITCARD', 'COD', 'DIRECTDEPOSIT', 'QUOTE', 'PROPRIETARY', 'ACCOUNT', 'NONE') No 'NONE' 15 Specifies the kind of method used by the payment type. This dictates when the payment type can be used to make payments. Set to either:
  • UNPAID
    Denotes when no payment has been made
  • CREDITCARD
    Payment is made with a credit card, through the credit card payment networks.
  • COD
    Cash On Delivery. Payment is made at the point when goods are delivered and exchanged hands with cash.
  • DIRECTDEPOSIT
    Payment is made via direct deposit bank transfer between bank accounts.
  • QUOTE
    No payment is required to be made since only a quote is to be raised.
  • PROPRIETARY
    Payment is made through an specific organisation's own proprietary payment system, such as PayPal, Afterpay, Zippay, or other proprietary payment system.
  • ACCOUNT
    Payment is to be made based on the customer account payment terms. This may allow for payment to be made at the end of a time period, such as monthly, or at a specified date of the month.
  • NONE
    No payment method has been specified or not required.

HTTP Request Raw Example:

Below is an example Payment Type Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=27 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3,
    "resultStatus": 1,
    "message":"",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 4,
    "configs":{"dataFields":"keyPaymentTypeID,paymentTypeCode,paymentTypeLabel,description,paymentMethod"},
    "dataRecords":
        [
        {
            "keyPaymentTypeID":"123"
        },
        {
            "keyPaymentTypeID":"456",
            "paymentTypeCode": "WEBCC",
            "paymentTypeLabel":"Credit Card",
            "description": "Credit Card payment made through a website",
            "paymentMethod": "CREDITCARD"
        },
        {
            "keyPaymentTypeID":"765",
            "paymentTypeCode": "DD",
            "paymentTypeLabel": "Direct Deposit",
            "description": "Payment made using a direct deposit bank transfer",
            "paymentMethod": "DIRECTDEPOSIT"
        },
        {
            "keyPaymentTypeID":"6765",
            "paymentTypeCode": "AC",
            "paymentTypeLabel": "On Account",
            "description": "Payment will be made at a time based on aggreed upon account terms",
            "paymentMethod": "ACCOUNT"
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the payment type data. See API Native Programming Libraries.
  • Typically payment types data only needs to be imported by organisations when a new type of payment type is made available by an organisation.
  • Payment Types need to be imported before Customer Account data to ensure that accounts can be assigned to their allowed payment types.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import. For more details on costs see Trading Tokens and Pricing for more details.

Import Sell Units

The Import Organisation Data endpoint can be called by an organisation to import a list of sell units into the SQUIZZ.com platform. Sell units describe how quantities of products can be bundled together. For example a sell unit called "Each" that describes a product being sold as an individual unit. Another sell unit called "Pack" could be created that describes multiple quantities of of product bundled together into a pack. Any number of sell units can be created, each with their own label. This import allows generic named sell units to be imported, such as "each", "pack", "carton", "container", "box". Then separately these sell units can be assigned to each product in the Product Import endpoint, with each product describing the label of the sell unit specific to the product. So an "each" sell unit could be assigned to a product, but the product would label the "each" sell unit as "drum", and the "pack" sell unit as "box of 6 drums".

Sell Units can be linked to each other in a hierarchy. This hierarchy can be used to allow customers to switch between sell units for a product, and the quantities will adjust accordingly based on the quantity of one sell unit that makes up another. For example if a "pack" sell unit has its parent sell unit set to "each", then if a product defines that 6 "each" quantities make up 1 "pack" sell unit, then if the customer changes the product being purchased from 1 pack to the each sell unit, then the value 6 will update in the quantity box. A sell unit can specify if it is the base sell unit, this means that it is top of the sell unit hierachy and represents an individual quantity. All other sell units at all levels of the hierarchy can indicate how many base sell unit quantities make up a sell unit. Sell units can also specify if they should be priced based on calculating the amount of base sell units quantities that make up a sell unit. This can reduce the amount of pricing records that need to be imported.

Sell Units are conditionally required to be imported by an organisation first before any product, product price-level unit pricing. price-level quantity pricing, or customer account pricing data is imported.

The endpoint needs to POST a list of sell unit records in the Sell Unit Ecommerce Standards Document(ESD) JSON data format. The endpoint will return an general Ecommerce Standards Document in the JSON data format that indicates if the sell units were successfully imported or not. Sell Units can only be imported by an organisation if it has enough trading tokens to covert the costs of the sell unit data import.See Trading Tokens and Pricing for more details.

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

Data Type Sell Unit
Field Name Data Type Mandatory Default Value Max Length Description
keySellUnitID STRING Yes [EMPTY STRING] 50 Unique identifier of the sell unit record that the organisation has set. Ensure that each sell unit has this unique key identifier across all of a sell units. The keySellUnitID  could be based on an internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier, or otherwise identified by a code created by a person.
sellUnitCode STRING No [EMPTY STRING] 50 The human known code of the sell unit This may or may not be unique, but typically each sell unit record will have its own unique code.
sellUnitLabel STRING No [EMPTY STRING] 50 Label of the sell unit. Allows people to understand what the sell unit is, or the kind of sell unit that a stock quantity represents. Eg. "Each:, "Pack", "Box", "Container", "Ship Load"
baseQuantity DECIMAL No 1 14.4 The quantity of the base sell unit that the sell unit is made up of. If the sell unit is a base sell unit then set to 1. This must be a positive value.
parentQuantity DECIMAL No 1 14.4 The quantity of the sell unit's parent sell unit that the sell unit is made up of. This is only required if the keySellUnitParentID is assigned to a sell unit.
isBaseUnit ENUM('Y','N') No 'Y' 1 If set to 'Y' - Yes then indicates that the sell unit is the base sell unit and representatives a single quantity of product stock.
keySellUnitParentID STRING No NULL 50 Set to a keySell UnitID of another sell unit that it may be linked to. This allows a sell unit to be linked to a parent sell unit in the sell unit hierarchy. Set to null to denote that the sell unit is not linked to any other.

HTTP Request Raw Example:

Below is an example Sell Unit Document being imported by the API endpoint.

POST https://api.squizz.com/rest/1/org/import_esd/3042EXAMPLEGSESSIONID342?import_type_id=2 HTTP/1.1
Host: api.squizz.com
Content-Type: application/json

{
    "version": 1.3,
    "resultStatus": 1,
    "message":"",
    "dataTransferMode": "COMPLETE",
    "totalDataRecords": 8,
    "configs":{"dataFields":"keySellUnitID,sellUnitCode,sellUnitLabel,isBaseUnit,keySellUnitParentID"},
    "dataRecords":
    [
        {
            "keySellUnitID":"2",
            "sellUnitCode":"EA",
            "sellUnitLabel":"EACH",
            "isBaseUnit":"Y"
        },
        {
            "keySellUnitID":"3",
            "sellUnitCode":"PK",
            "sellUnitLabel":"Pack",
            "isBaseUnit":"N",
            "keySellUnitParentID":"2"
        },
        {
            "keySellUnitID":"4",
            "sellUnitCode":"CT",
            "sellUnitLabel":"Carton",
            "isBaseUnit":"N",
            "keySellUnitParentID":"3"
        },
        {
            "keySellUnitID":"5",
            "sellUnitCode":"CN",
            "sellUnitLabel":"Container",
            "isBaseUnit":"N",
            "keySellUnitParentID":"4"
        },
        {
            "keySellUnitID":"6",
            "sellUnitCode":"SHIP",
            "sellUnitLabel":"Ship Load",
            "isBaseUnit":"N",
            "keySellUnitParentID":"5"
        },
        {
            "keySellUnitID":"7",
            "sellUnitCode":"TRAIN",
            "sellUnitLabel":"Train Load",
            "isBaseUnit":"N",
            "keySellUnitParentID":"5"
        },
        {
            "keySellUnitID":"8",
            "sellUnitCode":"HOUR",
            "sellUnitLabel":"Hour",
            "isBaseUnit":"Y"
        },
        {
            "keySellUnitID":"9",
            "sellUnitCode":"LABOUR PACK",
            "sellUnitLabel":"Pack Of Labour Hours",
            "keySellUnitParentID":"8",
            "isBaseUnit":"N"
        }
    ]
}

HTTP Response Example:

Below is an example Document returned by the API endpoint. resultStatus 1 indicates a successful response

{"resultStatus":"1", "configs":{"api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS"}, "message":""}

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 import the sell unit data. See API Native Programming Libraries.
  • Typically sell unit data only needs to be imported by organisations when a new type of sell unit is added to an organisation's business system.
  • Many business systems have a fixed number of sell units that don't change, and if that's the case then the sell unit data would only need to be imported once.
  • Sell Units need to be imported before Product, Product Price-Level Unit Pricing, Price-Level Quantity Pricing and Customer Account Pricing data to ensure that products and their pricing can be assigned to sell units.
  • In the request use the config object's dataFields attribute to list the fields that should be updated for existing records previously imported. Any fields not in this list will be ignored from being updated, or have data saved against.
  • Look at the list of result_codes at the top of this document to see how the different errors could be returned by this endpoint.
  • Note that there are trading token costs to call the endpoint and import. For more details on costs see Trading Tokens and Pricing for more details.