Merchanter API - Customers

Updated at December 21st, 2022

+ More

CustomerAccounts

GET operations
- /CustomersAccounts –Retrieve information relating to customer accounts under the current user account’s ledger
  - Parameters
    - HTTP header type
      - If-Modified-Since – a UTC timestamp (format ‘yyyy-MM-dd HH:mm:ss’). Only customer accounts that have been created or modified since this timestamp will be returned
    - Query type
      - Where – a filter expression string with ANDed filters. Available filters are
        
        HasParent – does the customer account have a parent account? true/false
        
        IsDefaultCurrency – is the customer account in home currency? true/false
        
        IsEcommerceDepot – does the customer account belong to an ecommerce depot? true/false

E.g. Where=HasParent==false&&IsDefaultCurrency==true&&IsEcommerceDepot==true

page – page number. Up to100 customer accounts 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	50	Customer account code	[ { "Code": "", "Name": "", "CreditLimit": 0.00, "OnOrderValue": 0.00, "LedgerBalance": 0.00, "UnpostedPaidValue": 0.00, "CreditStatus": "", "CreditMessage": "", "PaymentTerms": { "DaysToPaymentDue": 0, "MonthsToPaymentDue": 0, "MonthlyAccount": false, "PaymentTermsBasis": "" }, "SalesRep": { "Name": "", "ShortName": "" }, "Depot": { "Code": "", "IsEcommerceDepot": false }, "VATCode": "", "AccountType": "", "OrderReferenceEssential": false, "AgedBalanceCurrent": 0.00, "AgedBalanceMonth1": 0.00, "AgedBalanceMonth2": 0.00, "AgedBalanceMonth3": 0.00, "AgedBalanceMonth4": 0.00, "CustomerPricingType": { "Name": "", "Code": "" }, "SalesContact": { "EmailAddress": "" }, "InvoicingAddress": { "AddressLine1": "", "AddressLine2": "", "City": "", "PostalCode": "", "PhoneNumber": "", "Country": { "Country_ISO3166_1": { "CountryCode_2": "" } } }, "DeliveryAddresses": [ { "AddressLine1": "", "AddressLine2": "", "City": "", "PostalCode": "", "PhoneNumber": "", "Country": { "Country_ISO3166_1": { "CountryCode_2": "" } } } ], "changedDate": "1900-01-01T00:00:00.000Z" } ]
Name	String	60	Customer account name
CreditLimit	Decimal		Credit limit
OnOrderValue	Decimal		Gross sales value sum (including VAT) of all uninvoiced orders less any payments made
LedgerBalance	Decimal		Current account balance of the sales ledger
UnpostedPaidValue	Decimal		Total amount of unallocated cash payments not yet posted to the sales ledger
CreditStatus	String		Credit status – In_Credit, Warning, Over_Credit, On_Hold, On_Stop, Cancelled
CreditMessage	String	100
VATCode	String	1	Customer VAT type – C (EC Sales), E (Export), G (Group), H (Home sales), I (Internal), X (Exempt)
AccountType	String		Account type – Account, CashOnly, Internal, TradeCountereCashSale, Commission
OrderReferenceEssential	Boolean		Does the customer require a reference number against each order?
AgedBalanceCurrent	Decimal		Aged debt balance – current period
AgedBalanceMonth1	Decimal		Aged debt balance – previous period
AgedBalanceMonth2	Decimal		Aged debt balance – 2 periods ago
AgedBalanceMonth3	Decimal		Aged debt balance – 3 periods ago
AgedBalanceMonth4	Decimal		Aged debt balance – 4 periods ago & earlier
changedDate	Datetime		Date & time of last update
PaymentTerms
- DaysToPaymentDue	Integer		Number of days till payment due
- MonthsToPaymentDue	Integer		Number of months till payment due
- MonthlyAccount	Boolean		Monthly account terms?
- PaymentTermsBasis	String		Payment terms basis – Days, Months, MonthsPlusDays
SalesRep
- Name	String	40	Full name of sales rep
- ShortName	String	20	Shorter name of sales rep
Depot
- Code	String	2	Depot code
- IsEcommerceDepot	Boolean		Ecommerce depot?
CustomerPricingType
- Name	String	200	Customer price band name
- Code	String	2	Customer price band code
SalesContact
- EmailAddress	String	200
InvoicingAddress
- AddressLine1	String	30
- AddressLine2	String	30
- City	String	30
- PostalCode	String	10
- PhoneNumber	String	30
- Country
- - Country_ISO3166_1
- - - CountryCode_2	String	2	ISO 3166-1 country code
DeliveryAddresses (array)
- AddressLine1	String	30
- AddressLine2	String	30
- City	String	30
- PostalCode	String	10
- PhoneNumber	String	30
- Country
- - Country_ISO3166_1
- - - CountryCode_2	String	2	ISO 3166-1 country code

/CustomerAccounts/Prices –Retrieve customer special pricing information for products under the current user account’s ledger
- Parameters
  - Query type
    - Where – a filter expression string with ANDed filters. Available filters are
      - HasParent – does the customer account have a parent account? true/false
      - IsDefaultCurrency – is the customer account in home currency? true/false
      - IsEcommerceDepot – does the customer account belong to an ecommerce depot? true/false
      - IsSpecial – is the product a special? true/false
      - SellOnline – is this an ecommerce product? true/false

E.g. Where=HasParent==false&&IsDefaultCurrency==true&&IsEcommerceDepot==true&&IsSpecial==false&&SellOnline==true

page – page number. Up to100 customer account special prices 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)
CustomerCode	String	50	Customer account code	[ { "CustomerCode": "", "ProductCode": "", "Price": 0.00 } ]
ProductCode	String	20	Product code
Price	Decimal		Nett special price (per stock unit of measure) for this customer account and product

Attribute Name

Data Type

Max Length

Notes

Response Body (JSON)

CustomerCode

String

Customer account code

[

{

"CustomerCode": "",

"ProductCode": "",

"Price": 0.00

}

]

ProductCode

String

Product code

Price

Decimal

Nett special price (per stock unit of measure) for this customer account and product

/CustomerAccounts/Transactions– Retrieve information for customer account transactions (invoices, credit notes) under the current user account’s ledger
- Parameters
  - HTTP header type
    - Date-From – a UTC timestamp (format ‘yyyy-MM-dd HH:mm:ss’). Only customer account transactions with a transaction date on or after this timestamp will be returned
    - If-Modified-Since – a UTC timestamp (format ‘yyyy-MM-dd HH:mm:ss’). Only customer account transactions that have been created or modified since this time stamp will be returned
  - Query type
    - Where – a filter expression string with ANDed filters. Available filters are
    - IsDefaultCurrency – is the customer account in home currency? true/false
    - IsEcommerceDepot – does the customer account belong to an ecommerce depot? true/false

E.g. Where=IsDefaultCurrency==true&&IsEcommerceDepot==true

page – page number. Up to100 customer account transactions 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)
Type	String		Transaction type – Sales_Invoice, Sales_Credit	[ { "Type": "", "Date": "1900-01-01T00:00:00.000Z", "Reference": "", "TotalValue": 0.00, "AmountPaid": 0.00, "AmountOutstanding": 0.00, "CustomerAccount": { "Code": "" }, "Invoice": { "DueDate": "1900-01-01T00:00:00.000Z ", "Dispatch": { "SalesOrder": { "OrderNumberWithSuffix": "", "CustomerReference": "", "Depot": { "Code": "" } } } }, "CreditNote": { "Invoice": { "Dispatch": { "SalesOrder": { "OrderNumberWithSuffix": "", "CustomerReference": "", "Depot": { "Code": "" } } } } } } ]
Date	Datetime		Transaction date (UTC)
Reference	String	30	Transaction reference number
TotalValue	Decimal		Total transaction amount (inc. VAT)
AmountPaid	Decimal
AmountOutstanding	Decimal
CustomerAccount
- Code	String	50	Customer account code
Invoice			Invoice information when type = Sales_Invoice
- DueDate	Datetime		Payment due date
- Dispatch
- - SalesOrder
- - - OrderNumberWithSuffix	String	30	Display representation of the internal order number (inc. suffix)
- - - CustomerReference	String	200	Reference number as supplied by the customer
- - - Depot
- - - - Code	String	2	Supplying depot code
CreditNote			Credit note information when type = Sales_Credit
- Invoice			Invoice to be credited
- - Dispatch
- - - SalesOrder
- - - - OrderNumberWithSuffix	String	30	Display representation of the internal order number (inc. suffix)
- - - - CustomerReference	String	200	Reference number as supplied by the customer
- - - - Depot
- - - - - Code	String	2	Supplying depot code

· POSToperations

o /CustomerAccounts/Payments– Create a new customer account payment

§ Request schema & body(JSON)

Attribute Name	Data Type	Max Length	Required	Notes	Request Body (JSON)
CustomerCode	String	50	Yes	Customer account code	{ “CustomerCode”: ””, “PaymentAmount”: 0.00, “PaymentDate”: ”1900-01-01T00:00:00.000Z”, “PaymentMethod”: ””, “PaymentReference”: “” }
PaymentAmount	Decimal		Yes	Total amount paid
PaymentDate	Datetime		No	Date of payment (UTC) – if not supplied, current date will be assumed
PaymentMethod	String	20	Yes	Tender type code
PaymentReference	String	20	Yes

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

Attribute Name	Data Type	Max Length	Notes	Response Body (JSON)
_ID	String	20	ID of payment object in Merchanter	{ “_ID”: “”, “CustomerCode”: ””, “PaymentAmount”: 0.00, “PaymentDate”: ”1900-01-01T00:00:00.000Z”, “PaymentMethod”: ””, “PaymentReference”: “” }
CustomerCode	String	50	Customer account code
PaymentAmount	Decimal		Total amount paid
PaymentDate	Datetime		Date of payment (UTC)
PaymentMethod	String	20	Tender type code
PaymentReference	String	20

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.

clients trader api

Merchanter API - Customers

Contact Us

CustomerAccounts

Authentication

Operations

Endpoints

Related Articles