Glengarry Wines B2B API

Introduction

Welcome to the Glengarry Wines business to business ("B2B") portal! This portal allows businesses to interact with Glengarry Wines and exchange information as defined in the application programming interface ("API") detailed below.

Overview

The B2B portal is open to other businesses on the secure Uniform Resource Locator ("URL") address https://b2b.glengarry.co.nz and essentially works by processing information exchange requests in either Javascript Object Notation ("JSON") or Extensible Markup Language ("XML") format received on extensions of that URL and then issuing processing outcome responses. For both requests and responses, the Multipurpose Internet Mail Extensions ("MIME") content type should be "application/json" or "application/xml" as appropriate for the specific call and the data should use Universal Character Set Transformation Format 8 bit ("UTF-8") character encoding.

The service is available 24 hours everyday with the exception of database maintenance periods which run every Sunday and Wednesday morning from approximately 4:00a.m. to 5:00a.m.

Information Exchange Requests

There are two parts to information exchange requests. The first is the URL that the request is sent to as that identifies the request. Requests that are currently supported are listed in the following table and detailed in more depth further on in this API.

Request Method	Request URL
Order Information	https://b2b.glengarry.co.nz/orderinfo
Order on Account	https://b2b.glengarry.co.nz/orderplace
Order Pickup Stores	https://b2b.glengarry.co.nz/orderpickupstores
Order with Payment	https://b2b.glengarry.co.nz/orderpay
Order Status	https://b2b.glengarry.co.nz/orderstatus
Stock Download	https://b2b.glengarry.co.nz/stockdownload
Stock Level	https://b2b.glengarry.co.nz/stocklevel
Purchase Order	https://b2b.glengarry.co.nz/purchaseorder
Purchase Stock Available	https://b2b.glengarry.co.nz/stockavailable

The second part of the information exchange request is the data sent to the URL. In the case of information retrieval requests then data needs to consist of a JSON or XML object that identifies who the requester is so that the request can be validated and the appropriate information is sent in the response. In the case of information processing requests then the data needs to consist of a JSON or XML object that identifies who the requester is and also contains the information to be processed.

For JSON requests, the JSON is a JSON object containing a JSON object "user" and an optional JSON object "data". The structure of the data object will depend upon the particular information being exchanged as per the API. The user object needs to have JSON Strings "name" and "password" being the log in credential agreed with your Glengarry Wines account manager. An example of a JSON information retrieval request is:

{
	"user":{
		"name":"yourName",
		"password":"yourPassword"
	}
}

Information Exchange Responses

The response JSON is a JSON object containing a JSON object "response". The structure of the response object is specified in the table below:

Key Name	Value Type	Specification
method	string	The information exchange method/service called, which will correspond to the URL that the request was sent to
status	string	The outcome of the information exchange being either "ok" or "error"
comment	string	Optional - in the case of errors the comment should be a description of the error to assist with debugging
data	array / object	Contains information retrieved or outcomes of processing as per the API for the particular information exchange method/service called. Data should not be interacted with / parsed if status is not ok i.e. status is an error

An abbreviated example of a JSON information retrieval response is:

{
	"response":{
		"method":"stockdownload",
		"status":"ok",
		"comment":"",
		"data":[
		...
		]
	}
}

Stock Download

Stock download is an information retrieval request involving sending a JSON user object to the URL https://b2b.glengarry.co.nz/stockdownload as discussed in the Information Exchange Requests and Information Exchange Responses sections above.

The structure of the data component of the response object is an array of JSON objects each having the structure specified in the table below:

Key Name	Value Type	Specification
stockcode	string	The Glengarry Wines stockcode for supplying this item as a single pack. Refer to pack for the number of individual units in a pack. A stockcode may be prefaced by "KIT" where the item is sold as a kit.
casecode	string	The Glengarry Wines case stockcode for supplying this item as a case of packs. Refer to casepack for the number of individual units in a case
brand	string	The brand name of this stock item
stockname	string	The name of this stock item
description	string	A description of this stock item
notes	string	(Tasting) notes pertaining to this stock item
variety	string	The variety of this stock item
style	string	The production style of this stock item
region	string	The region of the country that this stock item is produced in
country	string	The country that this stock item is produced in
vintage	string	The vintage year of this stock item's production - may be an empty string or "NV" for non-vintage
volume	string	The volume of each unit of this stock item inclusive of measurement unit such as "ml" for millilitres and "L" for litre
imagesmall	string	The name of the smaller size image file on the Glengarry web server
imagelarge	string	The name of the larger size image file on the Glengarry web server
pack	integer	The number of individual units in a pack of this stock item. Pack can be 1 such as for a single bottle of wine
casepack	integer	The number of individual units in a case of this stock item
awards	array	An array of strings being the names of any awards bestowed upon this stock item
stocklevel	double	The number of packs of this stock item currently in stock
stockreservation	double	The number of packs of this stock item currently in stock that are exclusively reserved for you to sell. This information may not be able to be retrieved at the time in which case a negative number will be returned. This means that stockreservation should only be used if it is 0.00 or a positiive number.
price	double	The current price in New Zealand dollars to buy a pack of this stock item from Glengarry Wines. By default the price is exclusive of freight and Goods and Services Tax ("GST")
caseprice	double	The current price in New Zealand dollars to buy a case of this stock item from Glengarry Wines. By default the price is exclusive of freight and Goods and Services Tax ("GST")
active	string	Will have the value "Y" if Glengarry Wines is currently offering this item for sale to you otherwise you are unable to purchase it

Stock Level

Stock level is an information retrieval request involving sending user and data JSON objects to the URL https://b2b.glengarry.co.nz/stocklevel as discussed in the Information Exchange Requests and Information Exchange Responses sections above. For a stock level request the data object must contain a JSON string of the stockcode that the stock level is to be returned for. An abbreviated example of the request JSON object is as follows:

{
	"user":{
	...
	},
	"data":{
		"stockcode":"yourStockcode"
	}
}

The structure of the data component of the response object is a JSON object having the structure specified in the table below:

Key Name	Value Type	Specification
stockcode	string	The Glengarry Wines stockcode for supplying this item as a single pack. Refer to pack for the number of individual units in a pack. A stockcode may be prefaced by "KIT" where the item is sold as a kit. "BAD CODE" should be returned for an invalid stockcode
pack	integer	The number of individual units in a pack of this stock item. Pack can be 1 such as for a single bottle of wine. -1 should be returned for an invalid stockcode
stocklevel	double	The number of packs of this stock item currently in stock
stockreservation	double	The number of packs of this stock item currently in stock that are exclusively reserved for you to sell. This information may not be able to be retrieved at the time in which case a negative number will be returned. This means that stockreservation should only be used if it is 0.00 or a positive number

Order on Account

Order on Account is an information exchange request involving sending user and data JSON objects to the URL https://b2b.glengarry.co.nz/orderplace as discussed in the Information Exchange Requests and Information Exchange Responses sections above. With an order on account the accounting for payment is handled separately between Glengarry and you in the normal manner and that is what distinguishes this call from Order with Payment. For an order on account request the data object must contain a JSON object of the order details and a JSON array of the order items that are being ordered. An abbreviated example of the request JSON object is as follows:

{
	"user":{
	...
	},
	"data":{
		"orderdetails":{
		...
		},
		"orderitems":[
		...
		]
	}
}

The structure of the orderdetails JSON object is specified in the table below: (note, by default the order's grand total can be calculated as the sum of all order items' quantity x price plus freight plus GST. GST inclusive processing must be agreed with Glengarry)

Key Name	Value Type	Specification
orderref	string	The unique order identifier that has been assigned to this order (truncated at 20 characters). This reference will be returned in a successful order transaction together with the Glengarry Wines orderid to enable the order to be looked up on both systems
recipient	string	The name of the delivery recipient for this order (truncated at 100 characters). The order courier label will state recipient and delivery1 - delivery4
delivery1	string	The first line of the delivery address for this order (truncated at 30 characters)
delivery2	string	The second line of the delivery address for this order (truncated at 30 characters)
delivery3	string	The third line of the delivery address for this order (truncated at 30 characters)
delivery4	string	The fourth line of the delivery address for this order (truncated at 30 characters)
instructions	string	Courier delivery instructions for this order (truncated at 250 characters)
freight	double	The amount of freight that has been assigned to this order. By default freight is GST exclusive

The structure of the JSON objects within the orderitems JSON array is specified in the table below:

Key Name	Value Type	Specification
stockcode	string	The Glengarry Wines stockcode for supplying this item either as a pack or as a case of packs. A stockcode may be prefaced by "KIT" where the item is sold as a kit.
description	string	The description of what is being ordered (truncated at 40 characters)
quantity	integer	The number of stockcode packs/cases being ordered
price	double	The price of the stockcode packs/cases being ordered. By default price is GST exclusive

The structure of the data component of the response object is a JSON object providing information upon the outcome of the order placement and a web order number for reference where the order has been successfully placed. The structure is specified below: (note, orderid is an integer whereas your orderref is returned as a string)

{
	"response":{
		"method":"orderplace",
		"status":"ok",
		"comment":"",
		"data":{
			"orderid":glengarryOrderNumber,
			"orderref":"yourOrderNumber"
		}
	}
}

Order Pick Up Stores

Order Pick Up Stores is an information retrieval request involving sending a user JSON object to the URL https://b2b.glengarry.co.nz/orderpickupstores as discussed in the Information Exchange Requests and Information Exchange Responses sections above. With an order pick up stores the store id returned becomes the storepickup within an order with payment.

The structure of the data component of the response object is a JSON array of JSON objects each having the structure specified in the table below::

Key Name	Value Type	Specification
id	integer	The unique identifier for this store that must be used as the storepickup within an order with payment for an order to be picked up from this store
name	string	The name that Glengarry uses for this store
city	string	The city that this Glengarry store is located in to allow stores to be grouped by city
url	string	A URL for more information about this store on the Glengarry Wines web site including information on contact phone, address with map, and opening hours

Order with Payment

Order with Payment is an information exchange request involving sending user and data JSON objects to the URL https://b2b.glengarry.co.nz/orderpay as discussed in the Information Exchange Requests and Information Exchange Responses sections above. With an order with payment the call must contain the necessary information for a credit card to be charged for the order and that is what distinguishes this call from Order on Account. For an order with payment request the data object must contain JSON objects for the order details, payment details, payment object (for encrypted payment information) and a JSON array of the order items that are being ordered. An abbreviated example of the request JSON object is as follows:

{
	"user":{
	...
	},
	"data":{
		"orderdetails":{
		...
		},
		"paymentdetails":{
		...
		},
		"paymentobject":{
		...
		},
		"orderitems":[
		...
		]
	}
}

Key Name	Value Type	Specification
orderref	string	The unique order identifier that has been assigned to this order (truncated at 20 characters). This reference will be returned in a successful order transaction together with the Glengarry Wines orderid to enable the order to be looked up on both systems
ordertype	string	Optional. A type of order identifier that may be needed by your processing system.
recipient	string	The name of the delivery recipient for this order (truncated at 100 characters). The order courier label will state recipient and delivery1 - delivery4
delivery1	string	The first line of the delivery address for this order (truncated at 30 characters)
delivery2	string	The second line of the delivery address for this order (truncated at 30 characters)
delivery3	string	The third line of the delivery address for this order (truncated at 30 characters)
delivery4	string	The fourth line of the delivery address for this order (truncated at 30 characters)
deliveryCountry	string	Optional. The delivery country with a default of "New Zealand"
instructions	string	Courier delivery instructions for this order (truncated at 250 characters)
signfor	string	Should be set as "Y" to require someone at the delivery address to sign for the courier delivery
storepickup	integer	The Glengarry store id if the order is to be picked up from a store. Should be set as -1 for standard courier delivery to customer
freight	double	The amount of freight that has been assigned to this order. Should be set as 0.00 for a pickup from store order and otherwise dependent upon the delivery location. By default freight is GST exclusive.
contactname	string	A contact name for issues relating to the order - specifically stock fulfilment and payment. Can be the same as recipient
contactemail	string	A contact email address for issues relating to the order - specifically stock fulfilment and payment
contactphone	double	A contact telephone number for issues relating to the order - specifically stock fulfilment and payment
callcentreassist	string	Should be set as "Y" if the Glengarry Call Centre should contact the customer prior to dispatching the order using contactemail / contactphone
recipientemail	string	A contact email address for issues relating to the delivery of the order - can be the same as contactemail
recipientphone	double	A contact telephone number for issues relating to the delivery of the order - can be the same as contactphone

The structure of the JSON objects within the paymentdetails JSON array is specified in the table below: (note, where data is instead contained in the paymentobject as agreed with Glengarry then that data should be set as an empty string / 0 integer here - what is required is that the combination of paymentdetails and paymentobject are sufficient for the credit card to be processed)

Key Name	Value Type	Specification
cardtype	string	The credit card type which can be a reward programme card where a system for using reward points as been pre-arranged with Glengarry
cardname	string	The name on the credit card
cardnumber	integer	The credit card number
cardcvv	integer	The credit card security code (CSC) / card verification data (CVD) / card verification value (CVV or CVV2) / card verification value code (CVVC) / card verification code (CVC or CVC2) / verification code (V-code or V code) / card code verification (CCV) / signature panel code (SPC)
cardexpirymonth	integer	The credit card's expiry month where 1 = January and 12 = December
cardexpiryyear	integer	The credit card's expiry year starting from 2000 as 0 and incrementing by 1 for every subsequent year
processcurrency	string	An optional reference that may be needed for processing payments where multi-currency has been agreed and specified with Glengarry
processref	string	An optional reference that may be needed for processing payments

The structure of the JSON object for paymentobject is specified in the table below: (note, where data is contained in the paymentobject as agreed with Glengarry but is incomplete then the missing details need to be contained in paymentdetails - what is required is that the combination of paymentdetails and paymentobject are sufficient for the credit card to be processed)

Key Name	Value Type	Specification
payload	string	The data for credit card payment processing that has been encrypted with a cypher agreed between Glengarry and you.

The structure of the JSON objects within the orderitems JSON array is specified in the table below:

Key Name	Value Type	Specification
stockcode	string	The Glengarry Wines stockcode for supplying this item either as a pack or as a case of packs. A stockcode may be prefaced by "KIT" where the item is sold as a kit.
description	string	The description of what is being ordered (truncated at 40 characters)
quantity	integer	The number of stockcode packs/cases being ordered
price	double	The price of the stockcode packs/cases being ordered. By default price is GST exclusive

{
	"response":{
		"method":"orderplace",
		"status":"ok",
		"comment":"",
		"data":{
			"orderid":glengarryOrderNumber,
			"orderref":"yourOrderNumber"
		}
	}
}

Order Information

Order Information is an information retrieval request involving sending user and data JSON objects to the URL https://b2b.glengarry.co.nz/orderinfo as discussed in the Information Exchange Requests and Information Exchange Responses sections above. For an order information request the data object must contain a JSON integer of the order number that the order information is to be returned for. There will be a delay of approximately 5-10mins after an order is placed before order information will return data for it. Additionally, an error "unavailable" will be returned if the accounting information cannot be retrieved at the time. An abbreviated example of the request JSON object is as follows:

{
	"user":{
	...
	},
	"data":{
		"order":yourWebOrderNumber
	}
}

The structure of the data component of the response object is a JSON array of JSON objects each having the structure specified in the table below that contains information upon all of the individual items that have been ordered:

Key Name	Value Type	Specification
salesorder	integer	The Glengarry Wines sales order number that uniquely identifies this order
stockcode	string	The Glengarry Wines stock code that identifies this item
description	string	The Glengarry Wines invoice description for this item
quantityordered	double	The quantity of packs of this item that have been ordered
quantitysupplied	double	The quantity of packs of this item that have been supplied
quantityinvoiced	double	The quantity of packs of this item that have been invoiced
quantitycancelled	double	The quantity of packs of this item that have been cancelled
quantitybackorder	double	The quantity of packs of this item that are on back order
unitprice	double	The price of packs of this item
discount	double	Any discount applied to packs of this item for this order
unitpricediscounted	double	The price of packs of this item inclusive of any discount
type	string	Contains information for this item where it is part of a kit i.e. a group of items supplied together
location	integer	An identifier of the Glengarry Wines location dispatching this order

Order Status

Order Status is an information retrieval request involving sending user and data JSON objects to the URL https://b2b.glengarry.co.nz/orderstatus as discussed in the Information Exchange Requests and Information Exchange Responses sections above. For an order status request the data object must contain a JSON integer of the order number that the order status is to be returned for. There will be a delay of approximately 5-10mins after an order is placed before order status will return data for it. Additionally, an error "unavailable" will be returned if the accounting information cannot be retrieved at the time. An abbreviated example of the request JSON object is as follows:

{
	"user":{
	...
	},
	"data":{
		"order":yourWebOrderNumber
	}
}

The structure of the data component of the response object is a JSON array of JSON objects each having the structure specified in the table below:

Key Name	Value Type	Specification
salesorder	integer	The Glengarry Wines sales order number that uniquely identifies this order
timestamp	string	The time that an update to the processing status of this order was recorded. Note, the data is a string in the format "dd MMM yyyy HH:mm:ss" so it can be parsed as a date using that format if required (format is self-explanatory with MMM being a three letter month designator and HH being the hour in the day 0-23).
update	string	A string denoting the new status of the order as it passing through order processing. Status updates include: (note, if updates are being interpreted / compared then they should be converted to lower/upper case or a case insensitive comparator should be used) Order Edited Order Manifested Shipped (additional information on the identity of the shipper should be included) Ticket (additional information on the courier ticket number should be included) Cases Shipped Order Killed
trackbarcode	string	The courier tracking barcode relating to this order

Purchase Order

Purchase Order is an information exchange request involving sending user and data in XML format to a supplier's B2B URL f.ex https://b2b.yourdomain.co.nz/purchaseorder and compling with the supplier's authentication credential requirements. For a Purchase Order request the data contains an XML nodes of order details. An abbreviated example of the request XML is as follows:

˂xml ...
	...
	˂data˃
		˂orderdetails˃
		...
			˂orderitems˃
				...
			˂/orderitems˃
		˂orderdetails˃
	˂/data˃

The structure of the orderdetails XML node is specified in the table below: (note, by default the order's grand total can be calculated as the sum of all order items' quantity x price plus freight plus GST. GST inclusive processing must be agreed with Glengarry)

Key Name	Value Type	Specification
purchaseorderref	string	The unique order identifier that has been assigned to this order. This reference will be returned in a successful order transaction together with the supplier's orderid to enable the order to be looked up on both systems
orderdate	string	Date of placing this Purchase Order
recipient	string	The name of the Glengarry delivery recipient for this order (truncated at 100 characters). The order courier label should state recipient and delivery1 - delivery4
recipientphone	string	Recipient's (mobile) phone number
recipientemail	string	Recipient's email address
delivery1	string	The first line of the delivery address for this order
delivery2	string	The second line of the delivery address for this order
delivery3	string	The third line of the delivery address for this order
delivery4	string	The fourth line of the delivery address for this order
instructions	string	Courier delivery instructions for this order (optional)
freight	double	The amount of freight that has been assigned to this order. By default freight is GST exclusive
location	integer	An identifier of the Glengarry Wines location receiving this order
creditor	integer	Glengarry Wines' creditor account number with the supplier

The structure of the XML within the orderitems is specified in the table below:

Key Name	Value Type	Specification
stockcode	string	The Glengarry Wines stockcode for this item either as a pack or as a case of packs. A stockcode may be prefaced by "KIT" where the item is sold as a kit.
sku	string	The Supplier's sku stockcode for supplying this item either as a pack or as a case of packs.
description	string	The description of what is being ordered (truncated at 40 characters)
quantity	integer	The number of stockcode packs/cases being ordered
price	double	The price of the stockcode packs/cases being ordered. By default price is GST exclusive

The structure of the response object is XML providing information upon the outcome of the order placement and a supplier's order number for reference where the order has been successfully placed. Ordered items are broken down into quantity that is being supplied versus back ordered etc The structure is specified below:

˂xml ...
	˂response˃
		˂method˃orderplace˂/method˃
		˂status˃ok˂/status˃
		˂comment˃˂/comment˃
		˂data˃
			˂orderid˃Supplier Order Number˂/orderid˃
			˂orderref˃Glengarry Purchase Order Ref˂/orderref˃
			˂contactname˃Name of Contact at Supplier˂/contactname˃
			˂contactemail˃Supplier Contact's email address˂/contactemail˃
			˂contactphone˃Supplier Contact's phone number˂/contactphone˃
			˂dispatchdate˃Supplier's dispatch date for this order˂/dispatchdate˃
			˂duedate˃Supplier's expected due date for this order˂/duedate˃
			˂orderitems˃
				˂orderitem˃
					˂sku˃Supplier SKU˂/sku˃
					˂stockcode˃Glengarry stockcode˂/stockcode˃
					˂description˃description˂/description˃
					˂quantityordered˃quantity ordered˂/quantityordered˃
					˂quantitysupplied˃quantity supplied˂/quantitysupplied˃
					˂quantityinvoiced˃quantity invoiced˂/quantityinvoiced˃
					˂quantitycancelled˃quantity cancelled˂/quantitycancelled˃
					˂quantitybackorder˃quantity backorder˂/quantitybackorder˃
					˂price˃price˂/price˃
				˂/orderitem˃
				...
			˂/orderitems˃
		˂/data˃
	˂/response˃