Merchanter API - Sales Orders

Updated at December 21st, 2022

+ More

Authentication

At the time of writing this document, the Merchanter API service uses basic authentication. This allows the clients to authenticate themselves by providing a username and password in the Authorization HTTP header.

Operations

Content Types

GET operations can send data in either XML (the default) or JSON format. If JSON is required, the request must be sent with an Accept HTTP header and the value “application/json”.

POST/PUT operations can receive data in either XML (the default) or JSON format. If JSON is required, the request must be sent with a Content-Type HTTP header and the value “application/json”.

Endpoints

The URL of every endpoint always starts with a base url:-

{Merchanter application url}/rest/api.merch/v1

Only the relative URL is shown for each endpoint.

Sales

· POSToperation

o /Sales/Orders – Create anew sales order at draft status

§ Request schema & body (JSON)

Attribute Name	Data Type	Max Length	Required	Notes	Request Body (JSON)
WebOrderRef	String	12	Yes	Order reference number as known to the ecommerce website	{ “WebOrderRef”: “”, “ERPOrderRef”: “”, “OrderDate”: "1900-01-01T00:00:00.000Z", “DeliveryDate”: "1900-01-01T00:00:00.000Z", “CustomerCode”: “”, “CustomerName”: “”, “EmailAddress”: “”, “OrderStatus”: “”, “CollectOrDeliver”: “”, “BranchCode”: “”, “CollectionBranchCode”: “”, “CollectionDetails”: “”, “TotalExVAT”: 0.00, “TotalInclVAT”: 0.00, “DeliveryCost”: 0.00, “DiscountTotal”: 0.00, “PaymentTaken”: false, “PaymentAmount”: 0.00, “PaymentMethod”: “”, “PaymentReference”: “”, “ShippingAddress”: { “Street1”: “”, “Street2”: “”, “Town”: “”, “County”: “”, “Country”: “”, “Postcode”: “”, “PhoneNr”: “” }, “Items”: [ { “ProductCode”: “”, “ItemDescription”: “”, “Quantity”: 0.000, “UnitPriceExVAT”: 0.00, “TotalInclVAT”: 0.00, “Specification”: “” } ] }
ERPOrderRef	String	10		Order reference number as known to Merchanter – not used at present
OrderDate	Datetime		Yes	Date of order placement (UTC time)
DeliveryDate	Datetime		No	Expected date of delivery (UTC time)
CustomerCode	String	50	Yes	Customer account code
CustomerName	String	60	No	Customer name (for guest customers – account code CASHWEB)
EmailAddress	String	200	Yes	Contact e-mail address
OrderStatus	String	20		Order status - not used at present
CollectOrDeliver	String	12	Yes	‘Collection’ or ‘Delivery’
BranchCode	String	2	Yes	Code of depot supplying the order (if delivery)
CollectionBranchCode	String	2	Yes	Code of depot supplying the order (if collection)
CollectionDetails	String	200	No	Supply instructions
TotalExVAT	Decimal		Yes	Total goods value of order excluding VAT
TotalInclVAT	Decimal		Yes	Order total value including VAT and delivery cost
DeliveryCost	Decimal		Yes	Total delivery cost including VAT
DiscountTotal	Decimal		Yes	Total discount value – discounts not currently supported so should always be zero
PaymentTaken	Boolean		Yes	Has a web payment been taken?
PaymentAmount	Decimal		Yes	Web payment amount – zero if no payment taken
PaymentMethod	String	20		Tender type code for web payment – only required if payment taken
PaymentReference	String	200	No	Web payment reference number
ShippingAddress
- Street1	String	30	No
- Street2	String	30	No
- Town	String	30	No
- County	String	40	No
- Country	String	30	No
- Postcode	String	10	No
- PhoneNr	String	20	No
Items (array)
- ProductCode	String	20	Yes	Product code
- ItemDescription	String	200	Yes	Item description
- Quantity	Decimal		Yes	Order quantity (per stock unit of measure)
- UnitPriceExVAT	Decimal		Yes	Unit price excluding VAT
- TotalInclVAT	Decimal		Yes	Total item value including VAT
- Specification	String		No	Timber specification (fixed cross-section) in the format Q1 x L1 \| Q2 x L2 \| Q3 x L3 \| … \| Qn x Ln where Q is the number of pieces, L is the spec length (to 1 decimal place) and n is the total number of lengths – only applies to timber products

The successful response schema & body (JSON) is as follows: -

Attribute Name	Data Type	Max Length	Notes	Response Body (JSON)
_ID	String	20	ID of sales order object in Merchanter	{ “_ID”: “”, “InternalOrderNumber”: 0, “OrderDate”: "1900-01-01T00:00:00.000Z", “SupplyDate”: "1900-01-01T00:00:00.000Z", “CustomerCode”: “”, “CustomerReference”: “”, “SupplyInstructions”: “”, “DeliveryType”: “”, “DepotCode”: “”, “SalesValue”: 0.00, “TaxValue”: 0.00, “TotalPlusVAT”: 0.00, “TransportCost”: 0.00, “DeliveryAddress”: { “Address1”: “”, “Address2”: “”, “Address3”: “”, “City”: “”, “County”: “”, “Postcode”: “”, “Name”: “”, “PhoneNr”: “” }, “Payment”: { “PaymentAmount”: 0.00, “PaymentDate”: "1900-01-01T00:00:00.000Z", “PaymentMethod”: “”, “PaymentReference”: “” }, “Items”: [ { “ProductCode”: “”, “ItemDescription”: “”, “OrderQuantity”: 0.000, “NettPrice”: 0.00, “SalesValue”: 0.00, “VATPercentage”: 0.00, “VATCode”: “”, “SpecificationSummary”: “” } ] }
InternalOrderNumber	Integer		Internal order number of sales order in Merchanter
OrderDate	Datetime		Date of order placement (UTC time)
SupplyDate	Datetime		Supply date (UTC time)
CustomerCode	String	50	Customer account code
CustomerReference	String	60	Customer reference
SupplyInstructions	String		Supply instructions
DeliveryType	String		Delivery type – Direct_to_site, Collected, Delivered, Cash, Credits, SuppliedNow
DepotCode	String	2	Supplying branch code
SalesValue	Decimal		Total sales value of order excluding VAT (in home currency)
TaxValue	Decimal		Total VAT value (in home currency)
TotalPlusVAT	Decimal		Total sales value of order including VAT (in home currency)
TransportCost	Decimal		Transport cost excluding VAT (in home currency)
DeliveryAddress
- Address1	String	30
- Address2	String	30
- Address3	String	30
- City	String	30
- County	String	40
- Postcode	String	10
- Name	String	30
- PhoneNr	String	30
Payment
- PaymentAmount	Decimal		Payment amount
- PaymentDate	Datetime		Date of payment (UTC)
- PaymentMethod	String	20	Tender type code
- PaymentReference	String	200	Payment reference number
Items (array)
- ProductCode	String	20	Product code
- ItemDescription	String	200	Item description
- OrderQuantity	Decimal		Order quantity (per order quantity unit of measure)
- NettPrice	Decimal		Nett unit price excluding VAT (in order currency per price unit of measure)
- SalesValue	Decimal		Nett sales value of the item (in order currency)
- VATPercentage	Decimal		VAT rate percentage
- VATCode	String	1	VAT rate code – C (EC Sales), E (Export), G (Group), L (Low), S (Standard), X (Exempt), Z (Zero)
- SpecificationSummary	String		Timber specification summary