Merchanter API v1.1 - Customer Accounts

Discover how to manage customer accounts effectively using the Merchanter API v1.1 for seamless integrations and operations.

Written by Ian Oldrey

Updated at June 18th, 2026

+ More

Table of Contents

POST operations CustomerAccountPayments CustomerAccountPrices CustomerAccountTransactions

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 to 100 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)
ID	String	20	Object ID	[ { “ID”: “”, "Code": "", "Name": "", "AccountType": "", "VATCode": "", "OrderReferenceEssential": false, "CreditLimit": 0.00, "CreditStatus": "", "CreditMessage": "", "OnOrderValue": 0.00, "UnpostedPaidValue": 0.00, "LedgerBalance": 0.00, "AgedBalanceCurrent": 0.00, "AgedBalanceMonth1": 0.00, "AgedBalanceMonth2": 0.00, "AgedBalanceMonth3": 0.00, "AgedBalanceMonth4": 0.00, "changedDate": "1900-01-01T00:00:00.000Z", "PaymentTerms": { “TermsDescription”: “”, “Settl”mentDis“ountPercentage": 0.00, "DaysToPaymentDue": 0, "MonthsToPaymentDue": 0, "MonthlyAccount": false, "PaymentTermsBasis": "" }, "Depot": { "Code": "", "IsEcommerceDepot": false }, "CustomerPricingType": { "Code": "", "Name": "" }, "SalesContact": { "EmailAddress": "" }, "InvoicingAddress": { "AddressLine1": "", "AddressLine2": "", "AddressLine3": "", "City": "", “County”: “”, "PostalCode": "", “CountryCode”: “”, "PhoneNumber": "", “FaxNumber”: “” }, "DeliveryAddresses": [ { "AddressLine1": "", "AddressLine2": "", "AddressLine3": "", "City": "", “County”: “”, "PostalCode": "", “CountryCode”: “”, "PhoneNumber": "", “FaxNumber”: “”, “ID”: “”, “Name”: “” } ], "SalesRep": { "Name": "", "ShortName": "" } } ]
Code	String	50	Customer account code
Name	String	60	Customer account name
AccountType	String		See enumerated type AccountType
VATCode	String	1	See enumerated type CustomerVATCode
OrderReferenceEssential	Boolean		Does the customer require a reference number against each order?
CreditLimit	Decimal		Credit limit
CreditStatus	String		See enumerated type CreditStatusEnum
CreditMessage	String	100
OnOrderValue	Decimal		Gross sales value sum (including VAT) of all uninvoiced orders less any payments made
UnpostedPaidValue	Decimal		Total amount of unallocated cash payments not yet posted to the sales ledger
LedgerBalance	Decimal		Current account balance of the sales ledger
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 (UTC)
PaymentTerms
- TermsDescription	String	40
- SettlementDiscountPercentage	Decimal
- DaysToPaymentDue	Integer		Number of days till payment due
- MonthsToPaymentDue	Integer		Number of months till payment due
- MonthlyAccount	Boolean		Monthly account terms?
- PaymentTermsBasis	String		See enumerated type PaymentTermsBasis
Depot
- Code	String	2	Depot code
- IsEcommerceDepot	Boolean		Ecommerce depot?
CustomerPricingType
- Code	String	2	Customer price band code
- Name	String	200	Customer price band name
SalesContact
- EmailAddress	String	200
InvoicingAddress
- AddressLine1	String	30
- AddressLine2	String	30
- AddressLine3	String	30
- City	String	30
- County	String	40
- PostalCode	String	10
- CountryCode	String	2	ISO 3166-1 country code
- PhoneNumber	String	30
- FaxNumber	String	30
- Country
- - Country_ISO3166_1
- - - CountryCode_2	String	2	ISO 3166-1 country code
DeliveryAddresses (array)
- AddressLine1	String	30
- AddressLine2	String	30
- AddressLine3	String	30
- City	String	30
- County	String	40
- PostalCode	String	10
- CountryCode	String	2	ISO 3166-1 country code
- PhoneNumber	String	30
- FaxNumber	String	30
- ID	String	20	Delivery address object ID
- Name	String	30	Customer name
- Country
- - Country_ISO3166_1
- - - CountryCode_2	String	2	ISO 3166-1 country code
SalesRep
- Name	String	40	Full name of sales rep
- ShortName	String	20	Shorter name of sales rep

/CustomerAccounts/{key} – Retrieve information relating to a specific customer account via its key
- Parameters
Path type
- key – either the ID of the object (if preceded by ID=) or the customer account code
  - Response schema & body – see above

POST operations

/CustomerAccounts – Create a new customer account
- Request schema & body (JSON)

Attribute Name	Data Type	Max Length	Required	Notes	Request Body (JSON)
Code	String		No	Customer account code – if supplied, must:- · Have valid characters (letters, digits, or special characters of underscore, ampersand or period) · Be no longer than the maximum length allowed for the customer account code (according to the linked accounts system) · Be unique (i.e. must not already be in use by another account) If not supplied, a customer account code will be auto-generated from the customer name based on the account code template defined in Merchanter.	{ “Code”: ””, “Name”: “”, “AccountType”: ””, “DeliveryType”: ””, “VATCode”: “”, “CommissionPercentage”: 0.00, “CurrencyCode”: “”, “DepotCode”: “”, “PaymentTerms”: { “SettlementDiscountPercentage”: 0.00, “DaysToPaymentDue”: 0, “MonthsToPaymentDue”: 0, “PaymentTermsBasis”: “” }, “CustomerAddress”: { “AddressLine1”: “”, “AddressLine2”: “”, “AddressLine3”: “”, “City”: “”, “County”: “”, “Postcode”: “”, “CountryCode”: “” }, “InvoicingAddress”: { “AddressLine1”: “”, “AddressLine2”: “”, “AddressLine3”: “”, “City”: “”, “County”: “”, “Postcode”: “”, “CountryCode”: “” }, “InvoiceContact”: { “Title”: “”, “FirstName”: “”, “LastName”: “”, “PhoneNumber”: “”, “MobileNumber”: “”, “FaxNumber”: “”, “EmailAddress”: “” }, “SalesContact”: { “Title”: “”, “FirstName”: “”, “LastName”: “”, “PhoneNumber”: “”, “MobileNumber”: “”, “FaxNumber”: “”, “EmailAddress”: “” } }
Name	String	60	Yes	Name of the customer – if name is required to be unique (because the linked accounts system requires it), name will also be validated for uniqueness
AccountType	String		No	See enumerated type AccountType – defaults to CashOnly
DeliveryType	String		No	See enumerated type DeliveryType – defaults to Delivered
VATCode	String	1	No	See enumerated type CustomerVATCode – defaults to H (home sales)
CommissionPercentage	Decimal		No	Only required when the AccountType is Commission. In this instance, percentage must be > 0 and <= 100.
CurrencyCode	String	3	No	ISO 4217 currency code – defaults to the home (base) currency
DepotCode	String	2	No	Code of the owning depot – defaults to the home depot of the user account
PaymentTerms				If not supplied, payment terms default to Nett 0 days.
- SettlementDiscountPercentage	Decimal		No	Settlement discount % - defaults to zero
- DaysToPaymentDue	Integer		No	Number of days from invoice date to payment due – defaults to zero
- MonthsToPaymentDue	Integer		No	Number of months from end of month of invoice date to payment due – defaults to zero. Example – if MonthsToPaymentDue is 1 and the invoice date is 20^th of January, the payment due date would be 28^th February.
- PaymentTermsBasis	String		No	See enumerated type PaymentTermsBasis – defaults to Days
CustomerAddress			Yes
- AddressLine1	String	30	Yes
- AddressLine2	String	30	No
- AddressLine3	String	30	No
- City	String	30	No
- County	String	40	No
- Postcode	String	10	No
- CountryCode	String	2	No	ISO 3166-1 country code – defaults to home country
InvoicingAddress			No	Only required if invoicing (billing) address is different to the customer address
- AddressLine1	String	30	Yes
- AddressLine2	String	30	No
- AddressLine3	String	30	No
- City	String	30	No
- County	String	40	No
- Postcode	String	10	No
- CountryCode	String	2	No	ISO 3166-1 country code – defaults to home country
InvoiceContact			No	Main/Accounts contact
- Title	String		No	See enumerated type Title
- FirstName	String	35	No
- LastName	String	35	No
- PhoneNumber	String	20	No
- MobileNumber	String	20	No
- FaxNumber	String	20	No
- EmailAddress	String	200	No	If supplied, must be a valid (correctly formed) email address
SalesContact			No	Sales contact
- Title	String		No	See enumerated type Title
- FirstName	String	35	No
- LastName	String	35	No
- PhoneNumber	String	20	No
- MobileNumber	String	20	No
- FaxNumber	String	20	No
- EmailAddress	String	200	No	If supplied, must be a valid (correctly formed) email address

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

Attribute Name

Data Type

Max Length

Notes

Response Body (JSON)

String

ID of customer account object in Merchanter

{

“ID”: “”,

“Code”: ””

}

Code

String

Customer account code in Merchanter

CustomerAccountPayments

POST operations
- /CustomerAccountPayments – 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	200	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	200

CustomerAccountPrices

/CustomerAccountPrices – 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 to 100 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

CustomerAccountTransactions

/CustomerAccountTransactions – 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 timestamp 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 to 100 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		See enumerated type SalesLedgerTransactionType	[ { "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

customer accounts merchanter

Merchanter API v1.1 - Customer Accounts

Contact Us

POST operations

CustomerAccountPayments

CustomerAccountPrices

CustomerAccountTransactions

Related Articles