Platform API Endpoint: Import Organisation Sales Order

Before reading on please ensure that you have understood the following topics:

• Getting Started/Overview
• Personal Signing Up To SQUIZZ.com
• Registering An Organisation
• Organisational Data
• Organisation Settings
• Trading Tokens and Pricing
• Connecting Business Systems
• Integrate Software Into SQUIZZ.com
• Platform API

The endpoint is used by an organisation to push one or more sales orders into the SQUIZZ.com platform and have it validated, optionally repriced, any sales order rules applied against it, and send across to connected freight and business systems.

This endpoint can be used by an organisation to have its sales orders that are raised across multiple selling systems, such as Ecommerce websites, 3rd party marketplaces, customer relationship management (CRM) systems, and any other business systems that create orders, have those orders flow through the SQUIZZ.com platform, perform the neccessary order validation, then have those sales orders be feed back into the back end system(s) that are already integrated into the SQUIZZ.com platform. 

This may reduce the amount of complexity by using existing business system integrations, saving time and money, whilst providing more automation. If a sales order is successfully imported, the endpoint will return a sales order containing the most up to date and accurate order data, including pricing data, product data, surcharge data, location data, and payment data.

Note that this endpoint should not be used by customer organisations to push through orders, since otherwise this would give permission for customers to set any pricing they wished for the sales orders, as well as other security issues. Instead customer organisations should use the Procure And Send Purchase Order To Supplier endpoint to push through their purchase orders, that can be correctly validated and priced based on their relationship to the supplying organisation. 

The API endpoint can be used by organisations who have been given permission to import sales orders to another connected organisation's customer accounts assigned to the importing organisation. This in effect allows the importing organisation to act like a sales representative, and import sales orders with pricing and other details. Typically this should only be allowed where there is a high level of trust between organisations.

The endpoint will look through each sales order given to it and try to find matching products that the organisation sells, as well as matching up the surcharges, locations, payment types, and customer account. Once all order data have been matched then if required the endpoint will try to reprice each product based on the quantities, sell unit and customer account assigned to the order. 

If repricing is not required then the endpoint will check that all product lines and surcharges have had all pricing set. Only if all products and surcharges in the sales orders have been priced, and all other data matched will the endpoint then create one or more sales orders for the organisation and have the sales orders be marked as submitted for processing by the supplier organisation. Note that the sales order rules will also be run, allowing additional surcharges location data, and freight providers to be optionally applied to the order. 

If successful the endpoint will then return each of the sales orders that were created, allowing the requesting system to know the costs of the sales order and be able to update the sales order based on the sales order totals.

Endpoint Requirements

To use this endpoint the following conditions need to be met:

• The organisation needs to have previously imported the customer accounts into SQUIZZ.com that sales orders are to be imported against
• The organisation needs have previously imported taxcodes, sell units, products, price-levels, price-level pricing/customer account pricing into SQUIZZ.com, that allows products to be validated and priced for the sales order product lines.
• If surcharges need to be applied against the order then the organisation needs to have previously imported surcharges into SQUIZZ.com. If the surcharges need to be repriced then sales order rules need to have been previously set up that specify when a surcharge should be applied against sales orders, and how the surcharges are priced.
• The organisation needs to have previously imported payment types into SQUIZZ.com, based on the payment types set within the sales order.
• The assigned customer account must be active and allow orders to be created against it
• Every product in the sales orders must match the organisation's products based on either of the following:
  • The sales order product line's Product Code must match either a previously imported product's Product Code
  • The sales order product line's Key Product ID must match either a previously imported product's Product Code
• If the imported sales order needs to be repriced then the pricing for the product must be previously imported. This includes price-level pricing that is assigned to the customer account that the order is associated to, or any customer account specific pricing for the order's customer account.
• If the imported sales order does not need to be repriced then the sales order product lines priceExTax, priceIncTax, priceTax, priceTotalExTax, priceTotalIncTax and priceTotalTax fields must have values set.
• If the imported sales order does not need to be repriced then the sales order surcharges need to have price values set for the priceExTax, priceIncTax and priceTax values.
• The sales order's currency must match the organisation's currency configured against the Organisation Settings.
• The organisation must  have enough trading tokens in the platform to cover the sales order transaction.
• If organisation is importing a sales order to another supplying organisation, then the importing organisation must be connected to the supplying organisation. The supplying organisation must have assigned a data sharing policy to the importing organisation that has the “Allow Sales Orders” Data Import permission set to Allow. The supplying organisation must have assigned the customer accounts to the importing organisation that they are allowed to import sales orders against.
• If an organisation is importing a sales order to another supplying organisation then the “supplier_org_id” must be set in the API endpoint request and contain the Organisation ID of the supplying organisation who's receiving the sales order.
• If an organisation is importing a sales order to another supplying organisation then the “customer_account_code” must be set in the API endpoint request if the supplying organisation has assigned multiple customer accounts to the importing organisation, and no customer account has been set as the default.

The sales orders being imported must be placed into the Body of the HTTP request in the form of a conforming Ecommerce Standards Sales Order Document JSON string. Before using this endpoint we recommend that you understand what the Ecommerce Standards Documents are and how you can send sales order data from your system into the standards document. It is highly recommended that any sales order data uploaded using this endpoint be compressed using the GZIP compression algorithm. Note that there are trading token costs to the organisation to have the sales orders imported, of which the organisation must have enough tokens to allow to do. See the Trading Tokens and Pricing page for more details.

HTTP Request

To see more information about the sales order fields that the endpoint supports you can find more information at Sales Order Records Fields.

Example Raw HTTP Request

HTTP Response

HTTP Response Example:

When making a HTTP request to the API endpoint, in the body of the HTTP request a Sales Order Ecommerce Standards Document (ESD) needs to be placed in its serialised JSON form, containing one or more sales order records within it.

Within the retrieved Sales Order JSON document, each sales order record is conforms to the Order Sale ESD Record format. The following table shows the record fields that this endpoint in the SQUIZZ.com API supports and reads from:

Sales Order Line Records

For each Sales Order Record in the lines property it may store an array of Sales Order Line Records, with each record specifying one type of product/goods that is to be ordered and a chosen quantity.

Each sales order line record is conforms to the Order Sale Line ESD Record format. The following table shows the line record fields that this endpoint in the SQUIZZ.com API supports and reads from:

Sales Order Surcharge Records

For each Sales Order Record in the surcharges property it may store an array of Order Surcharge Records, with each record specifying one type of surcharge that has been additionally costed against the order.

Each order surcharge record is conforms to the Order Surcharge ESD Record format. The following table shows the surcharge record fields that this endpoint in the SQUIZZ.com API supports and reads from:

Sales Order Payment Records

For each Sales Order Record in the payments property it may store an array of Order Payment Records, with each record specifying one type of payment that hsa been applied against an order.

Each order payment record is conforms to the Order Payment ESD Record format. The following table shows the payment record fields that this endpoint in the SQUIZZ.com API supports and reads from: