saveCustomer

Create a new customer or update customer information. Function can be used for manipulating both companies and persons. Some parameters only apply to one or another.

If the created or updated customer is a natural person and your account country is subject to the General Data Protection Regulation (GDPR), Erply logs the change in the customer information processing log.

Input parameters

Parameter name Description Possible value Required
trimInputData

Set this flag to 1 when passing user-supplied input.

When the flag is set, API will remove whitespace from the beginning and from the end of the following fields: companyName, companyName2, lastName, firstName, fullName, phone, mobile, email.

We may update the behavior of this flag in the future: remove whitespace from more fields or start doing other kinds of data sanitization. In any case, the purpose of the flag is to fix user errors. When the flag is applied, the saved data may be different from original input. Since this is undesirable in certain situations, the flag is off by default.

0 or 1
customerID ID of a customer. If this parameter is present, then the specified customer is updated. integer
***** If creating a new company, use parameter companyName or companyName2.
If creating a new person, use parameters firstName and lastName. Alternatively - if it is necessary to add data where person's name is not split into surname and given names, use parameter fullName.
One of three parameters - companyName, lastName, fullName - is required.
companyName When companyTypeID is not known, API will try to parse the type from the value. Value will be changed (type removed) when it is found.
When companyTypeID is known then value will be saved as given.
string
companyName2 Value will be always saved as given. When used without companyTypeID then the first available will be set.
When used together with companyName then companyName will always be used instead.
string
companyTypeID If is not set - company type ID will be calculated by analysing companyName for type-related parts.
If companyName2 is used then the first available will be set instead
integer
firstName string
lastName string
fullName string
personTitleID ID of a customer's title. integer
gender Gender: "male", "female" or empty string. For persons only. string
groupID Customer group ID. Use getCustomerGroups. If not specified, customer will be assigned to the first customer group in the list.
When updating existing customer, groupID must not be set to 0.
integer
code National ID number (for persons) / Registry code (for companies). string
vatNumber Customer's VAT number. string
email string
phone string
mobile string
fax string
skype string
imageContent Customer's image content in base64. Use base64_encode($imagefile) Image
imageMimeType Image mime-type, allowed types are image/gif and image/jpeg string
website string
bankName Name of customer's bank. string
bankAccountNumber Number of customer's bank account. string
bankIBAN IBAN number of customer's bank account. string
bankSWIFT BIC/SWIFT identifier of customer's bank account. string
birthday Person's birthday (not applicable to companies). Date (yyyy-mm-dd)
integrationCode Corresponding customer identifier in a system integrated with Erply (eg. accounting software) string
jobTitleID Person's job title ID. integer
companyID Use to indicate that this person is a contact person / an employee in a particular company.. integer
customerManagerID Customer manager (must be an employee, use getEmployees). integer
invoicePayerID Use to indicate that invoices to this customer must be addressed by default to another company. integer
paymentDays Default payment period for invoices. integer
penaltyPerDay Penalty for overdue invoices, expressed as % per day, eg. "0.5". Free text. string
credit Credit limit. Use system's default currency. integer
salesBlocked Indicates that this customer is not allowed to receive invoices (up-front cash payments only). 0 or 1, by default 0
referenceNumber Assign a reference number - if system is configured to use hand-created customer reference numbers. By default not necessary, since reference numbers are created automatically. string
customerCardNumber Assign the code of customer's loyalty/membership card. This code must match the sequence produced by card swipe. string
priceListID Assign the customer a price list (see getPriceLists). integer
priceListID2 Customer's price list 2. integer
priceListID3 Customer's price list 3. integer
priceListID4 Customer's price list 4. (only on accounts that have the extra fields enabled) integer
priceListID5 Customer's price list 5. (only on accounts that have the extra fields enabled) integer
euCustomerType Customer type. Possible values are "DOMESTIC", "EU", "EU_WITH_VAT", "OUTSIDE_EU". string
outsideEU DEPRECATED — euCustomerType is recommended instead. Indicate that this is a foreign customer, located outside EU. 0 or 1, by default 0
businessAreaID Customer's business area. Use getBusinessAreas. integer
countryID Country ID. Use getCountries. integer
taxOfficeID Tax office ID.

This is a Greece-specific field and can only be used on Greek accounts. Setting it on other accounts returns error code 1128.

To retrieve a list of tax offices, see getTaxOffices.
integer
notes string
username User name for webshop access. Before assigning user name, use API call validateCustomerUsername to verify that the user name is unique (no other customer has it yet). string
password Password for webshop access. string
flagStatus Whether the customer is flagged or not. Integer (1 or 0)
doNotSell Whether the customer is flagged as do not sell or not. Integer (1 or 0)
colorStatus Color that the customer entry is marked with. Possible values: "", "yellow", "red", "blue", "green". string
taxExempt Indicates this customer is a tax exempt organization. Integer (0 or 1)
partialTaxExemption Integer (0 or 1)
factoringContractNumber Factoring contract number. String (255)
paysViaFactoring Indicates this customer pays invoices via factoring. Integer (0 or 1)
twitterID string
facebookName string
creditCardLastNumbers Last 4 numbers of customer's credit card string
deliveryTypeID integer
signUpStoreID Location where customer was registered integer
homeStoreID Most commonly used location integer
primaryStoreID Can be used in an e-commerce integration, to store the customer’s preferred pickup locations, for example — if it is necessary to distinguish those from the customer’s preferred store for in-person shopping ("homeStoreID"). integer
secondaryStoreID Can be used in an e-commerce integration, to store the customer’s preferred pickup locations, for example — if it is necessary to distinguish those from the customer’s preferred store for in-person shopping ("homeStoreID"). integer
rewardPointsDisabled Indicates that this customer does not earn new reward points. 0 or 1, by default 0
customerBalanceDisabled Indicates that this customer ignores balance calculation. 0 or 1, by default 0
posCouponsDisabled Indicates that POS does not automatically print coupons to this customer. 0 or 1, by default 0
emailOptOut Indicates that this customer is opted-out customer. 0 or 1, by default 0
shipGoodsWithWaybills Indicates that for this customer, shipments should be (and may be) accompanied by a Waybill. At the end of the month, a summary Invoice can be issued for all the month's shipments and customer will pay then for all the shipments at once. (In the Sales module, there is a command "Create invoice from selected waybills"). If a customer does not have this flag, you should issue Invoice-Waybills instead, and the customer must pay for each shipment separately.
Field appears only if conf parameter enable_waybill_customers is set to 1
integer 0 or 1
useSuppliedIDForNewCustomer If the flag is set and the "customerID" parameter is present, API will create the customer record with the supplied ID if it does not exist. API will update the customer record with the supplied ID if it exists. Integer (1 or 0)
doNotUpdateLastModificationTime Integer (0 or 1)
**** Data exchange channels ****
emailEnabled Indicates whether the customer would like to get invoices on their email. 0 or 1, by default 1
eInvoiceEnabled Indicates whether the customer would like to get e-invoices. 0 or 1, by default 0
docuraEDIEnabled Integer (0 or 1)
**** E-invoicing settings ****
eInvoiceEmail Email address for e-invoices. If this is empty, then the regular email address is used. string
eInvoiceReference Customer reference for e-invoices. string
mailEnabled If e-invoice operator supports sending paper mails and this value is set to 1, then the operator is allowed to send the invoice by mail (additional charges might occur). 0 or 1, by default 0
operatorIdentifier string
EDI EDI code. string
PeppolID Peppol ID. string
**** EDI settings ****
ediType EDI type. Possible values: 2DOC, 4DOC, SPECIAL. string
GLN GLN. string
***** Additional attributes associated with this item.
Attributes must be supplied as a flat list, each attribute defined by the following set of three parameters. Replace # with set number (1, 2, 3, ...). When updating an existing entry, API will only update the attributes specified in input data and leave all other existing attributes unchanged. To delete an attribute, set its value to 'null' or 'undefined'.
*****
attributeName# Attribute name. Name can only contain the following symbols: A-Z, a-z, 0-9, dash and underscore. string
attributeType# Attribute type, possible types are 'text', 'int' and 'double'. By default 'text'. string
attributeValue# Value of the attribute. Set value to 'null' or 'undefined' to delete an attribute.
'text' attribute can be any string, maximum 255 characters.
'int' must be a signed 32-bit integer.
'double' must be a decimal number.
string
***** To store strings longer than 255 characters, use "long attributes". (All accounts might not have this capability (API returns error 1006). If necessary, please ask Erply customer support to turn this feature on.)

As with regular attributes, send parameters longAttributeName1 and longAttributeValue1 to store an attribute, longAttributeName2 and longAttributeValue2 to store another etc. The "#" symbol below should be replaced with numbers 1, 2, 3, etc.

When updating an existing entry, API will only update the attributes specified in input data and leave all other existing attributes unchanged. To delete an attribute, set its value to 'null' or 'undefined'.
*****
longAttributeName# Attribute name. Name can only contain the following symbols: A-Z, a-z, 0-9, dash and underscore. string
longAttributeValue# Value of the attribute. Set value to 'null' or 'undefined' to delete an attribute. String (65535)

Response

Field name Type Description
customerID integer
alreadyExists integer 0 or 1.