The Customers resource allows Customers to be viewed, created, and updated. An individual Customer’s details can be viewed, or updated by appending its identifier (a GUID formatted as XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) to the URI.
The full range of URIs and HTTP Verbs supported are:
Operation
HTTP Action
List of paginated Customers
GET /Customers/Page/{pageNumber}
View any Customer
GET /Customers/{CustomerGuid}
List all contacts for a specific Customer
GET /Customers/{CustomerGuid}/Contacts
Create or update a Customer
POST /Customers/{CustomerGuid}
Create a new Customer Contact
POST /Customers/{CustomerGuid}/Contacts
Update an existing Customer Contact
PUT /Customers/{CustomerGuid}/Contacts/{ContactGuid}
Only returns Customers that have a contact email that starts with the specified email address.
currency
Only returns Customers with currency code exactly matching the specified value.
customer
Returns Customers whose customer code or customer name contains the specified value. It is case-sensitive.
customerCode
Only returns Customers that start with the specific customer code.
customerName
Only returns Customers that start with the specific customer name.
customerType
Only returns Customers that matches the specified customer type.
includeAllContacts
Returns the first 100 contacts of each Customer record, if set to true. If set to false only the primary contact details will be returned as part of the response.
includeObsolete
Returns all Customers, including obsolete, if set to true. If set to false or if it is not specified then returns only active (ie. non-obsolete) Customers.
modifiedSince
Returns Customers created or modified since the specified date.
orderBy
Orders the list by LastModifiedOn or CreatedOn date. By default the list is ordered by CustomerCode
pageSize
Specifies the page size for pagination. Default page size is 200 customers.
Note: Requesting large numbers of customers can be susceptible to poor network performance. Please reduce the page size if you experience delayed requests.
salesOrderGroup
Only returns Customers with the specified sales order group.
sellPriceTier
Only returns Customers that are assigned to the specified sell price tier.
sort
Orders the list by CreatedOn date sorted in ascending or descending order.
stopCredit
Returns Customers who have had their credit stopped, if set to true. If set to false or if not specified, returns all customers.
xeroContactId
Only returns Customers that start with the specific Xero Contact Id.
Note: Date filters should be provided in the ISO format YYYY-MM-DD.
Filters are used by adding the filter and value to the URI:
/Customers?customerCode=ACME&includeObsolete=true
/Customers?orderBy=CreatedOn - returns Customers ordered by created on date sorted in ascending order
/Customers?orderBy=CreatedOn&sort=desc - returns Customers ordered by created on date sorted in descending order
Available Fields for GET Customers
Property
Type
Length
Addresses
Address
BankAccount
String
500
BankBranch
String
500
BankName
String
500
Contacts
Contact collection
ContactFirstName
String
500
ContactLastName
String
500
CreatedBy
String
50
CreatedOn
Nullable DateTime
CreditLimit
Decimal
Currency
Currency
CustomerCode
String
500
CustomerName
String
500
CustomerType
String
50
DDINumber
String
500
DefaultWarehouse
DefaultWarehouse
DeliveryInstruction
String
500
DeliveryMethod
String
50
DiscountRate
Nullable Decimal
Email
String
500
EmailCC
String
500
EORINumber
String
20
FaxNumber
String
500
GSTVATNumber
String
500
Guid
Guid
HasCreditLimit
Boolean
LastModifiedBy
String
50
LastModifiedOn
Nullable DateTime
MobileNumber
String
500
Notes
String
1024
Obsolete
Boolean
PaymentTerm
String
100
PhoneNumber
String
500
PrintInvoice
Nullable Boolean
PrintPackingSlipInsteadOfInvoice
Nullable Boolean
Reminder
String
1024
SalesOrderGroup
String
50
SalesPerson
SalesPerson
SellPriceTier
String
25
SellPriceTierReference
SellPriceTierReference
StopCredit
Boolean
Taxable
Nullable Boolean
TaxCode
String
50
TaxRate
Nullable Decimal
TollFreeNumber
String
500
Website
String
500
XeroCostOfGoodsAccount
String
500
XeroSalesAccount
String
500
Examples for GET /Customers
show xml example
show json example
GET Customer Contacts
Available Filters for GET Customer Contacts
Filter
Description
orderBy
Orders the list by LastModifiedOn or CreatedOn date. By default the list is ordered by Primary Contact then alphabetically by First Name, Last Name.
page
Specifies which page number will be shown.
pageSize
Specifies the page size for pagination, the default page size is 200 customer contacts.
Note: Requesting large numbers of customer contacts can be susceptible to poor network performance. Please reduce the page size if you experience delayed requests.
sort
Orders the list by CreatedOn date sorted in ascending or descending order.
Filters are used by adding the filter and value to the URI:
/Customers/{CustomersGuid}/Contacts?orderBy=CreatedOn&sort=asc - returns a customer’s contacts, ordered by created on date sorted in ascending order
Available Fields for GET Customer Contacts
Property
Type
Length
Notes
DeliveryAddress
String
500
Delivery Address name
DDINumber
String
500
EmailAddress
String
500
FaxNumber
String
500
ForInvoicing
Boolean
ForOrdering
Boolean
ForShipping
Boolean
FirstName
String
500
Guid
Guid
500
IsDefault
Boolean
LastName
String
500
MobilePhone
String
500
Notes
String
1024
OfficePhone
String
500
PhoneNumber
String
500
TollFreeNumber
String
500
Website
String
500
Examples for GET /CustomerContacts
show xml example
show json example
POST Customers
Available Fields for POST Customer
Note: Any changes to the Primary Contact, requires Primary contact details with ContactFirstName, ContactLastName, and/or Email to be supplied. Updates made to existing Primary Contact will overwrite existing information, fields left blank will be removed.