Web Service Endpoint: Send Customer Invoice To Customer

This API endpoint allows a supplying organisation to push through a customer invoice to a purchasing organisation, that is converted into a supplier invoice for the purchaser and can be sent to the purchaser's system for automatic importing

Topics

Prerequisites

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

Overview

The endpoint is used by a supplier organisation to push one or more invoices into the platform and have it be passed to a customer organisation, we it can then be imported back into the customer's business system. This allows organisations who supply goods and services to other organisations to automate the invoicing process, save time and money for both suppliers and customers. When a supplier organisation sends a "customer invoice" through this API endpoint, it will convert the customer invoice into a supplier invoice, and if the purchaser organisation requires it the invoice's lines can be matched up to the purchasers products, surcharges and taxcodes. This may then allow the invoice to be imported into the purchaser organisation's business system with its own codes.

HTTP Request

Headers
HTTP Method	POST
HTTP URL	https://api.squizz.com/rest/1/org/send_customer_invoice_to_customer/session_id?customer_org_id=[org_id]&supplier_account_code=[supplier_account_code]
Content-Type	application/json
Parameters	Data Type	Mandatory	Description
session_id	STRING	Yes	ID of the API session. Place the session ID within the URL
customer_org_id	STRING	Yes	ID of the organisation in the platform that is to recieve the invoice.
supplier_account_code	STRING	No	Code of the customer organisation's supplier account. The account code is only required if the customer organisation has assigned multiple supplier accounts (a.k.a. creditors or vendors) to the supplier organisation calling the endpoint.
Body	JSON	Yes	Body contains a Customer Invoice Ecommerce Standards Document that has one or more customer invoice records. The document is serialized into its JSON data string.

To see more information about the customer invoice fields that the endpoint supports you can find more information at Customer Invoice Records Fields.

Example Raw HTTP Request

POST https://api.squizz.com/rest/1/org/send_customer_invoice_to_customer/402934A8234E1B997D51F23974?supplier_org_id=342429EDABC3432498737 HTTP/1.1
Host: api.squizz.com
Content-Length: 3031
Content-Type: application/json

{
"resultStatus":"1",
"message":"The customer invoice data has been successfully obtained.",
"configs":{},
"dataTransferMode": "COMPLETE",
"version": 1.1,
"totalDataRecords": 1,
"dataRecords":
[
{
"keyPurchaseOrderID":"111",
"purchaseOrderCode":"POEXAMPLE-345",
"purchaseOrderNumber":"345",
"keySupplierAccountID":"2",
"supplierAccountCode":"ACM-002",
"supplierAccountName":"Acme Supplies",
"currencyISOCode": "AUD",
"deliveryContact":"Jane Doe",
"deliveryOrgName":"Acme Industries",
"deliveryEmail":"js@someemailaddress.comm",
"deliveryPhone":"+6144433332222",
"deliveryFax":"+6144433332221",
"deliveryAddress1":"Unit 5",
"deliveryAddress2":"22 Bourkie Street",
"deliveryAddress3":"Melbourne",
"deliveryPostcode":"3000",
"deliveryRegionName":"Victoria",
"deliveryCountryName":"Australia",
"deliveryCountryCodeISO2":"AU",
"deliveryCountryCodeISO3":"AUS",
"billingContact":"John Citizen",
"billingOrgName":"Acme Industries International",
"billingEmail":"ms@someemailaddress.comm",
"billingPhone":"+61445242323423",
"billingFax":"+61445242323421",
"billingAddress1":"43",
"billingAddress2":"High Street",
"billingAddress3":"Melbourne",
"billingPostcode":"3000",
"billingRegionName":"Victoria",
"billingCountryName":"Australia",
"billingCountryCodeISO2":"AU",
"billingCountryCodeISO3":"AUS",
"instructions":"Leave goods at the back entrance",
"isDropship":"N",
"lines":
[
{
"lineType":"PRODUCT",
"quantity": 4,
"priceExTax": 5.00,
"priceIncTax": 5.50,
"priceTax": 0.50,
"priceTotalExTax": 20.00,
"priceTotalIncTax": 22.00,
"priceTotalTax": 2.00,
"unitName": "EACH",
"productCode": "TEA-TOWEL-GREEN",
"productName": "Green tea towel - 30 x 6 centimetres" ,
"salesOrderProductCode": "SUPPLIER-TOWEL-GRN"

},
{
"lineType":"PRODUCT",
"quantity": 2,
"priceExTax": 5.00,
"priceIncTax": 5.50,
"priceTax": 0.50,
"priceTotalExTax": 10.00,
"priceTotalIncTax": 11.00,
"priceTotalTax": 1.00,
"unitName": "EACH",
"productCode": "TEA-TOWEL-BLUE",
"productName": "Blue tea towel - 30 x 6 centimetres",
"salesOrderProductCode": "SUP-TEA-TOWEL-BLUE"
}
]
}
]
}

HTTP Response

Parameters	Data Type	Description
Response Data Type	JSON

result	ENUM (SUCCESS or FAILURE)	Either "SUCCESS" or "FAILURE". If successful then the data was imported into the platform against the organsiation.
configs.api_version	DECIMAL	Version of the SQUIZZ.com platform's API used to handle the request
configs.result_code	STRING	Status code of trying to import the ESD document data. The following codes could be returned: SERVER_SUCCESS The customer invoices were successfully send, converted into supplier invoices and sent for processing in the customer organisation. SERVER_ERROR_ORG_DOES_NOT_EXIST The customer organisation with the given organisation ID could not be found or is not active within the platform. Check with the customer organisation that their organisation ID issued by the platform is correct. SERVER_ERROR_SESSION_INVALID The session used to call the endpoint has expired, or never existed. Look at calling the Create Session endpoint to get another session ID. SERVER_ERROR_ORG_NOT_BUYING The customer organisation is not currently buying on the platform. The customer organisation would need to change its Trading Status to Fully Trading or Buying Only to allow the invoices to be received. SERVER_ERROR_NO_ORG_SUPPLIER_ACCOUNT_SET The customer organisation has not assigned any supplier account to the supplier organisation. The customer organiation needs to import and assign the supplier organisation to a supplier account. SERVER_ERROR_NO_ORG_SUPPLIER_ACCOUNT_ASSIGNED The customer organisation has not assigned any supplier account to the supplier organisation. The customer organiation needs to import and assign the supplier organisation to a supplier account. SERVER_ERROR_INVOICE_LINE_NOT_MAPPED One or more of the lines in the customer invoices received cannot be mapped to the customer's products. See the "configs.invoices_with_unmapped_lines" attribute returned by the endpoint to determine the lines within the customer invoice that have been unmapped and may require a person to resolve. SERVER_ERROR_INVOICE_LINE_TAXCODE_NOT_MAPPED One or more of the line's taxcodes in the customer invoices received cannot be mapped to the customer's taxcodes. See the "configs.invoices_with_unmapped_line_taxcodes" attribute returned by the endpoint to determine the lines within the customer invoice that have been unmapped to any taxcodes and may require a person to resolve. SERVER_ERROR_INVOICE_SURCHARGE_NOT_MAPPED One or more of the surcharges in the customer invoices received cannot be mapped to the customer's surcharges. See the "configs.invoices_with_unmapped_surcharges" attribute returned by the endpoint to determine the surcharges within the customer invoice that have been unmapped and may require a person to resolve. SERVER_ERROR_INVOICE_SURCHARGE_TAXCODE_NOT_MAPPED One or more of the surcharge taxcodes in the customer invoices received cannot be mapped to the customer's taxcodes. See the "configs.invoices_with_unmapped_surcharge_taxcodes" attribute returned by the endpoint to determine the surcharge lines within the customer invoice that have been unmapped to a taxcode and may require a person to resolve. SERVER_ERROR_ORG_NOT_ENOUGH_CREDITS The supplier or customer organisation does not have enough trading tokens within the platform to allow the supplier invoices to be created. Either the supplier organisation needs to purchase more trading tokens to allow it to send invoices through this endpoint, or the customer organisation needs to give permission for the invoice to be paid by their trading tokens and that they have enough trading tokens. SERVER_ERROR_DATA_JSON_WRONG_CONTENT_TYPE The content type set in the HTTP Request Header is missing or not correctly set to "application/json". Ensure that the body of the HTTP request also has the customer invoice data set in the JSON dat format.
configs.invoices_with_unmapped_lines	STRING	Contains a comma delimited list of key value pairs (that each are colon delimited) that specifies the index of the customer invoice record and the index of the line within the record that could not be matched to a customer's product. For example if this value was set to "1:2,1:3,4:0", Then it would specify that the 2nd customer invoice record (index 1) within the dataRecords array of the invoices uploaded in the endpoint request has lines 3 and 4 that have unmapped products (line indexes 2 and 3), and for the 5th customer invoice record (record index 4) the 1st order line has an unmapped product (line index 0).
configs.invoices_with_unmapped_line_taxcodes	STRING	Contains a comma delimited list of key value pairs (that each are colon delimited) that specifies the index of the customer invoice record and the index of the line within the record that contains a taxcode that could not be matched to to one of the customer's taxcodes. For example if this value was set to "1:2,1:3,4:0", Then it would specify that the 2nd customer invoice record (index 1) within the dataRecords array of the invoices uploaded in the endpoint request has lines 3 and 4 that have unmapped taxcodes (line indexes 2 and 3), and for the 5th customer invoice record (record index 4) the 1st order line has an unmapped taxcode (line index 0).
configs.invoices_with_unmapped_surcharges	STRING	Contains a comma delimited list of key value pairs (that each are colon delimited) that specifies the index of the customer invoice record and the index of the surcharge within the record that could not be matched to a customer's surcharge. For example if this value was set to "1:2,1:3,4:0", Then it would specify that the 2nd customer invoice record (index 1) within the dataRecords array of the invoices uploaded in the endpoint request has surcharges 3 and 4 that have unmapped surcharges (surcharge line indexes 2 and 3), and for the 5th customer invoice record (record index 4) the 1st order surcharge has an unmapped surcharge (surcharge line index 0).
configs.invoices_with_unmapped_surcharge_taxcodes	STRING	Contains a comma delimited list of key value pairs (that each are colon delimited) that specifies the index of the customer invoice record and the index of the surcharge that contains a taxcode that could not be matched to a customer's taxcode. For example if this value was set to "1:2,1:3,4:0", Then it would specify that the 2nd customer invoice record (index 1) within the dataRecords array of the invoices uploaded in the endpoint request has surcharges 3 and 4 that have unmapped taxcodes for surcharges (surcharge line indexes 2 and 3), and for the 5th customer invoice record (record index 4) the 1st order surcharge has an unmapped surcharge taxcode (surcharge line index 0).
dataRecords	JSON ARRAY	List of Supplier Invoice Ecommerce Standards Records. Each record contains details of the corresponding customer's supplier invoice that was generated from each customer invoice. These details include supplier invoice number, invoice line pricing, surcharge prices (such as freight and shipping)

HTTP Response Example:

{"result":"SUCCESS", "api_version":"1.0.0.0", "result_code":"SERVER_SUCCESS", "dataRecords":[list_of_supplier_invoice_records]}

Customer Invoice Record Fields

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

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

Field Name	Data Type	Mandatory	Default Value	Max Length	Description
Data Type	Purchase Order Record
keyPurchaseOrderID	STRING	Yes	[EMPTY STRING]	50	Unique identifier of the purchase order that uniquely identifies the order within the customer organisation's system. The keyPurchaseOrderID may be the same as the purchase order code, or may be based on an different internal unique identifier created in a business system's database, such as an auto-incrementing number, UUID, or GUID identifier.
keySupplierAccountID	STRING	No	[EMPTY STRING]	50	The unique identifier of the supplier account that the customer organisation has linked to the purchase order.
supplierAccountCode	STRING	Yes	[EMPTY STRING]	60	Code the supplier account that has been linked to the purchase order.
purchaseOrderNumber	STRING	No	[EMPTY STRING]	50	Number of the purchase order, may or may not be a unique identifier of the order. The code will be used as a reference in the sales order of the supplier organisation, and may be used find the associated supplier sales order.
createdDate	LONG INTEGER	No	0		Date that the order was created. 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.
instructions	STRING	No	[EMPTY STRING]	21,844	Text describing the instructions on how to handle or deliver the order. May contain comments on the order.
deliveryOrgName	STRING	No	[EMPTY STRING]	50	Name of the organisation that the ordered products/goods will be delivered to.
deliveryContact	STRING	No	[EMPTY STRING]	50	Contact person at the delivery address where the ordered products/goods will be delivered to.
deliveryEmail	STRING	No	[EMPTY STRING]	100	Email address that notifications about the order delivery are to be sent to.
deliveryAddress1	STRING	No	[EMPTY STRING]	90	1st address field to deliver the ordered products/goods to. Typically set the unit/apartment number, building name, street number and/or street name.
	STRING	No	[EMPTY STRING]	90	2nd address field to deliver the ordered products/goods to. Typically set the steet number and name within this field.
deliveryAddress3	STRING	No	[EMPTY STRING]	90	3rd address field to deliver the ordered products/goods to. Set the suburb, city or town within this field.
deliveryRegionName	STRING	No	[EMPTY STRING]	70	Name of the region, state or province to deliver the ordered products/goods to. If the field is not set then it may be auto filled by the platform based on the delivery post code/zip code.
deliveryCountryName	STRING	No	[EMPTY STRING]	70	Name of the country, state or province to deliver the ordered products/goods to. If the field is not set then it may be auto filled based on the country that the customer organisation is registered to.
deliveryPostcode	STRING	No	[EMPTY STRING]	20	Postcode or zip code that the ordered products/goods are delivered to.
billingContact	STRING	No	[EMPTY STRING]	90	Contact person where the order will be billed to.
billingOrgName	STRING	No	[EMPTY STRING]	50	Name of the organisation that the order will be billed to.
billingEmail	STRING	No	[EMPTY STRING]	100	Email address that notifications about billing of the order are to be sent to.
billingAddress1	STRING	No	[EMPTY STRING]	90	1st address field to bill the order to. Typically set the unit/apartment number, building name, street number and/or street name.
billingAddress2	STRING	No	[EMPTY STRING]	90	2nd address field to bill the order to. Typically set the steet number and name within this field.
billingAddress3	STRING	No	[EMPTY STRING]	90	3rd address field to bill the order to. Set the suburb, city or town within this field.
billingRegionName	STRING	No	[EMPTY STRING]	70	Name of the region, state or province to bill the order to. If the field is not set then it may be auto filled by the platform based on the billing post code/zip code.
billingCountryName	STRING	No	[EMPTY STRING]	70	Name of the country, state or province to bill the order to. If the field is not set then it may be auto filled based on the country that the customer organisation is registered to.
billingPostcode	STRING	No	[EMPTY STRING]		Postcode or zip code that the billing of the order will be sent to.
isDropship	ENUM (Y,N)	No	N	1	Denotes if the order should be delivered direct from the supplier to a specified consumer, as set in the delivery fields. If set to Y then the order is marked as a drop ship order. The supplier may put the organisation's name of who is raising this order onto the packaging to make it look like the ordered products/goods came from the requesting organisation.
lines	ARRAY (ESDRecordOrderPurchaseLine)	Yes	[Empty ARRAY]	-	An array of Purchase Order Line ESD Records that specify the products/goods that are to be ordered and purchased.

Purchase Order Line Records

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

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

Field Name	Data Type	Mandatory	Default Value	Max Length	Description
Data Type	Purchase Order Line Record
lineType	ENUM (PRODUCT)	Yes	[EMPTY STRING]	-	Specifies the type of entities being ordered. Set to PRODUCT to denote that a physical or non-physical product is being purchased.
keyProductID	STRING	No	[EMPTY STRING]	50	Unique identifier of the product within the customer organisation's system. The keyProductID may be the same as the productCode, 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.
productCode	STRING	Yes	[EMPTY STRING]	50	Code that allows the product to be identified within the customer organisation's system. Typically this code is unique to each product that the organisation purchases. The product code may also be known as a Stock Keeping Unit (SKU), item number, product ID, or item code in certain systems. This code may be used to try to match it to one of the supplier organisation's products where an exact match exists.
productName	STRING	No	[EMPTY STRING]	50	Number of the purchase order, may or may not be a unique identifier of the order. Name of the purchasing organisation's product. The name typically contains natural words that allow it easily understood by people on what the product is, or does.
quantity	DECIMAL	Yes	0.0000	14,4	The quantity to be ordered/purchased. Set the quantity based on the base sell unit of the supplier organisation's product. If the quantity is set at 0 or less then the quantity will be changed to 1.
priceTotalIncTax	DECIMAL	No	0.0000	14,4	The purchaser's expected total price of the line for all quantities ordered, including taxes.
priceTotalExTax	DECIMAL	No	0.0000	14,4	The purchaser's expected total price of the line for all quantities ordered, excluding taxes.
priceTotalTax	DECIMAL	No	0.0000	14,4	The purchaser's expected total tax cost of the line for all quantities ordered.
salesOrderProductCode	STRING	No	[EMPTY STRING]	60	Set to the product code of the supplier organisation's product. This code may be used to try to match it to one of the supplier organisation's products where an exact match can be found to the supplier's product code.

Document last modified on the 22nd November 2023