Merchanter API v1.1 - Sales

Discover how to effectively utilise the Merchanter API v1.1 for optimising sales processes and enhancing transaction management.

Written by Ian Oldrey

Updated at June 18th, 2026

+ More

GET operations
- /Sales/Orders/{key} – Retrieve information relating to a specific sales order via its key
  - Parameters
Path type
- key – either the ID of the object (if preceded by ID=) or the order number display string
  - Response schema & body – see response of POST operation

POST operations
- /Sales/Orders – Create a new sales order at draft status
  - Request schema & body (JSON)

Attribute Name	Data Type	Max Length	Required	Notes	Request Body (JSON)
WebOrderRef	String	30	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”: “”, “CustomerReference”: “”, “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”: “”, “Street3”: “”, “Town”: “”, “County”: “”, “Country”: “”, “Postcode”: “”, “PhoneNr”: “” }, “Items”: [ { “ProductCode”: “”, “ItemDescription”: “”, “Quantity”: 0.000, “UnitPriceExVAT”: 0.00, “TotalInclVAT”: 0.00, “Specification”: “”, “AdditionalComments”: “” } ] }
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)
CustomerReference	String	200	No	Customer’s own order reference
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
- Street3	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) – volume is rounded to 3 d.p.
- UnitPriceExVAT	Decimal		Yes	Unit price excluding VAT
- TotalInclVAT	Decimal		Yes	Total item value including VAT
- Specification	String		No	Timber specification string – only applies to timber products 1) fixed cross-section format Q₁ x L₁ \| Q₂ x L₂ \| Q₃ x L₃ \| … \| Q_n x L_n where Q is the number of pieces, L is the spec length (in metres) and n is the total number of lengths 2) mixed widths format (each size group is separated by a semi-colon) W₁ : Q₁ x L₁ \| Q₂ x L₂ \| Q₃ x L₃ \| … \| Q_n x L_n ; W₂ : Q₁ x L₁ \| Q₂ x L₂ \| Q₃ x L₃ \| … \| Q_n x L_n where W is the spec width (in mm), Q is the number of pieces, L is the spec length (in metres) and n is the total number of lengths 3) mixed sizes format (each size group is separated by a semi-colon) T₁ x W₁ : Q₁ x L₁ \| Q₂ x L₂ \| Q₃ x L₃ \| … \| Q_n x L_n ; T₂ x W₂ : Q₁ x L₁ \| Q₂ x L₂ \| Q₃ x L₃ \| … \| Q_n x L_n where T is the spec thickness (in mm), W is the spec width (in mm), Q is the number of pieces, L is the spec length (in metres) and n is the total number of lengths
- AdditionalComments	String	4000	No	Item level notes

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

Attribute Name	Data Type	Max Length	Notes	Response Body (JSON)
ID	String	20	Object ID	{ “ID”: “”, “OrderDate”: "1900-01-01T00:00:00.000Z", “SupplyDate”: "1900-01-01T00:00:00.000Z", “OrderStatus”: “”, “CustomerCode”: “”, “CustomerReference”: “”, “SupplyInstructions”: “”, “DeliveryType”: “”, “DepotCode”: “”, “SalesValue”: 0.00, “TaxValue”: 0.00, “TotalPlusVAT”: 0.00, “TransportCost”: 0.00, “DeliveryAddress”: { “AddressLine1”: “”, “AddressLine2”: “”, “AddressLine3”: “”, “City”: “”, “County”: “”, “PostalCode”: “”, “Name”: “”, “PhoneNumber”: “” }, “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”: “”, “AdditionalComments”: “” } ], “OrderNumberWithSuffix”: “” }
InternalOrderNumber	Integer		Internal order number of sales order in Merchanter
OrderDate	Datetime		Date of order placement (UTC time)
SupplyDate	Datetime		Supply date (UTC time)
OrderStatus	String		Order status – see enumerated type OrderStatusEnumeration
CustomerCode	String	50	Customer account code
CustomerReference	String	200	Customer reference
SupplyInstructions	String		Supply instructions
DeliveryType	String		Delivery type – see enumerated type DeliveryType
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
- AddressLine1	String	30
- AddressLine2	String	30
- AddressLine3	String	30
- City	String	30
- County	String	40
- PostalCode	String	10
- Name	String	30
- PhoneNumber	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 – see enumerated type OrderItemVATCode
- SpecificationSummary	String		Timber specification summary
- AdditionalComments	String
OrderNumberWithSuffix	String	30	Display representation of the order number (& suffix if > 0)

salesapi merchant

Merchanter API v1.1 - Sales

Contact Us

Related Articles