Merchanter API - Products
Written by Ian Oldrey
Updated at December 21st, 2022
Table of Contents
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.
Products
· GEToperations
o /Products – Retrieveinformation relating to products under the current user account’s ledger
· HTTPheader type
o If-Modified-Since – a UTCtimestamp (format ‘yyyy-MM-dd HH:mm:ss’). Only products that have been createdor modified since this timestamp will be returned
· Querytype
o Where – a filterexpression string with ANDed filters. Available filters are
§ IsSpecial – is the product a special(special products are usually non-stock items for one-off sales)? true/false
§ SellOnline – is this an ecommerceproduct? true/false
E.g.Where=IsSpecial==false&&SellOnline==true
o page – page number. Up to100 products will be returned per call when the page parameter is used e.g.page=1.
§ Response schema & body (JSON)
Attribute Name |
Data Type |
Max Length |
Notes |
Response Body (JSON) |
Code |
String |
20 |
Product code |
[ { "Code": "", "StockUoM": "", "Description": "", "LiveStatus": "", "ProductType": "", "StockDecimalPrecision": "", "IsSpecial": false, "SellOnline": false, "BoxFactor": 0, "ProductSubGroup": { "ProductSubGroupName": "", "ProductSubGroupShortName": "" }, "ProductGroup": { "ProductGroupName": "", "ProductGroupShortName": "" }, "SupplierProductCodes": [ { "Code": "", "Supplier": { "Code": "" } } ], "PreferredSupplier": { "Code": "" } } ] |
StockUoM |
String |
|
Primary stock unit of measure – Unit_s_, Sheet_s_, Piece_s_, Metre_s_ |
|
Description |
String |
|
Full product description |
|
LiveStatus |
String |
|
Product live status – Live, Withdrawn, Archived, Catalogue |
|
ProductType |
String |
|
Product type – Goods, Service, Special |
|
StockDecimalPrecision |
String |
|
Decimal precision of stock – dp0, dp1, dp2, dp3 |
|
IsSpecial |
Boolean |
|
Is this a special product? |
|
SellOnline |
Boolean |
|
Is this an ecommerce product? |
|
BoxFactor |
Integer |
|
Number of units per box |
|
ProductGroup |
|
|
|
|
- ProductGroupName |
String |
40 |
Full name of product analysis group |
|
- ProductGroupShortName |
String |
20 |
Shorter name of product analysis group |
|
ProductSubGroup |
|
|
|
|
- ProductSubGroupName |
String |
40 |
Full name of product analysis subgroup |
|
- ProductSubGroupShortName |
String |
20 |
Shorter name of product analysis subgroup |
|
SupplierProductCodes (array) |
|
|
|
|
- Code |
String |
200 |
Supplier product code |
|
- Supplier |
|
|
|
|
- - Code |
String |
50 |
Supplier account code |
|
PreferredSupplier |
|
|
|
|
- Code |
String |
50 |
Supplier account code |
o /Products/Prices – Retrievepricing information for products under the current user account’s ledger
· HTTPheader type
o If-Modified-Since – a UTCtimestamp (format ‘yyyy-MM-dd HH:mm:ss’). Only products that have been createdor modified since this timestamp will be returned
· Querytype
o Where – a filterexpression string with ANDed filters. Available filters are
§ IsSpecial – is the product a special?true/false
§ SellOnline – is this an ecommerceproduct? true/false
E.g.Where=IsSpecial==false&&SellOnline==true
o page – page number. Up to100 products will be returned per call when the page parameter is used e.g.page=1.
§ Response schema & body (JSON)
Attribute Name |
Data Type |
Max Length |
Notes |
Response Body (JSON) |
ProductCode |
String |
20 |
Product code |
[ { "ProductCode": "", "BasePrice": 0.00, "VATRate": 0.00, "ProductPrices": [ { "PriceBandCode": "", "Price": 0.00 } ] } ]
|
BasePrice |
Decimal |
|
Base selling price |
|
VATRate |
Decimal |
|
VAT rate percentage |
|
ProductPrices (array) |
|
|
|
|
- PriceBandCode |
String |
2 |
Price band code |
|
- Price |
Decimal |
|
Nett price (per stock unit of measure) for price band |