Open2b version 7.8

customers

customers.find
customers.get
customers.authenticate
customers.count
customers.create
customers.update
customers.delete

customers.find

Returns the customers that meet the given conditions.

Request

Admin SDK
Admin.api('commerce.customers.find', request, function(response) { … });

HTTP POST
/api/v13/commerce.customers.find

{
  "conditions" : { // returns the customers …
    "ids" : [ 70371, 39628, … ], // … with these identifiers - int(1…)
    "code" : "TF78123", // … with this code - string(0…32)
    "canLogin" : true, // … that can login or not on site - bool
    "group" : 3, // … associated with this customer group - int(1…255)
    "email" : "johnsmith@acme.com", // … with this email - string(3…120)
    "personalCode" : "SH239IBA", // … with this personal code - string(1…20)
    "companyCode" : "ACME80193", // … with this company code - string(1…20)
    "keywords" : "acme", // … with these keywords in code, name, personal code, company code or email - string(1…120)
    "country" : "GB", // … with this country - string(2)
    "stateProv" : "LND", // … with this province, state or county - string(1…3)
    "labels" : [ 1, 3, … ], // … with these labels - int(1…32)
    "after" : 70371 // … with identifier after this value - int(0…)
  },
  "fields" : [ "id", "code", … ], // fields to return - string
  "order" : [ "id" ], // sort order of returned customers, can contain "id", "-id", "code", "-code", "email", "-email",
                      // "canLogin", "-canLogin", "hasPassword", "-hasPassword", "fullName", "-fullName",
                      // "country", "-country", "creationTime", "-creationTime", "updateTime", "-updateTime",
                      // "group" and "-group" - string
  "limit" : 10, // maximum number of customers to return - int(1…)
  "first": 0 // index of the first customer to return - int(0…)
}

Response

{
  "status" : "ok",
  "customers" : [ {
    "id" : 37091, // identifier - int(1…)
    "code" : "TF78123", // code - string(0…32)
    "canLogin" : true, // indicates if she can login on site - bool
    "hasPassword" : true, // indicates if she has a password - bool
    "encryptedPassword" : "foY5/eLc93Wu5…", // encrypted password - string(45)
    "locale" : "en-GB", // locale (ISO code) of the customer, region is not mandatory - string(2…5)
    "creationTime" : "2020-05-21 16:49:13", // creation time - datetime
    "loginTime" : "2020-12-13 12:05:44", // last login time (can be null) - datetime
    "updateTime" : "2020-12-05 09:24:01", // last update time - datetime
    "group" : 3, // associated customer group (id) - int(1…255)
    "collection" : 8, // catalog collection (id) (can be null) - int(1…)
    "collections" : [ 22, 54, … ], // additional collections (id) - int(1…)
    "wishList" : [ 340, 981, 18, … ], // products (id) in the customer's wish list - int(1…)
    "cart" : "RtRi8JWsxK…TMwTA1UJtg", // cart (token) (can be null) - string(32), // saved cart - string(32)
    "invoiceRecipient" : "AB7TR6K", // electronic invoice recipient code or PEC email address - string(0…256)
    "fullName" : "Investigations Inc", // Company name or first and last name - string(1…100)
    "billingAddress" : { // billing address
      "firstName" : "Sherlock", // first name - string(1…25)
      "lastName" : "Holmes", // last name - string(1…25)
      "personalCode" : "SH239IBA", // personal code - string(0…20)
      "companyName" : "Investigations Inc", // company name - string(0…100)
      "companyCode" : "INV8403MC1", // company code number - string(0…20)
      "companyCode2" : "7J BA3 006", // second company code number - string(0…20)
      "street1" : "221b Baker Street", // street, first row - string(1…60)
      "street2" : "", // street, second row - string(0…60)
      "city" : "London", // city - string(1…35)
      "postalCode" : "NW1 6XE", // postal code - string(1…20)
      "stateProv" : "LND", // state, province or county - string(0…3)
      "country" : "GB", // country (ISO code) - string(2)
      "phoneNumber" : "+44+207 2243688", // phone number - string(0…15)
      "mobileNumber" : "", // mobile number - string(0…15)
      "faxNumber" : "", // fax number - string(0…15)
      "email" : "holmes@inv-london.com" // email address - string(3…120)
    },
    "shippingAddress" : { // shipping address (can be null)
      "name" : "John", // recipient name - string(1…100)
      "street1" : "221b Baker Street", // street, first row - string(1…60)
      "street2" : "", // street, second row - string(0…60)
      "city" : "London", // city - string(1…35)
      "postalCode" : "NW1 6XE", // postal code - string(1…20)
      "stateProv" : "LND", // province, state or county - string(0…3)
      "country" : "GB" // country (ISO code) - string(2)
    }
  }, … ]
}

customers.get

Returns a customer given its identifier.

Request

Admin SDK
Admin.api('commerce.customers.get', request, function(response) { … });

HTTP POST
/api/v13/commerce.customers.get

{
  "id" : 37091, // identifier (required) - int(1…)
  "fields" : [ "id", "code", … ] // fields to return - string
}

Response

{
  "status" : "ok",
  "customer" : { // (can be null)
    "id" : 37091, // identifier - int(1…)
    "code" : "TF78123", // code - string(0…32)
    "canLogin" : true, // indicates if she can login on site - bool
    "hasPassword" : true, // indicates if she has a password - bool
    "encryptedPassword" : "foY5/eLc93Wu5…", // encrypted password - string(45)
    "locale" : "en-GB", // locale (ISO code) of the customer, region is not mandatory - string(2…5)
    "creationTime" : "2020-05-21 16:49:13", // creation time - datetime
    "loginTime" : "2020-12-13 12:05:44", // last login time (can be null) - datetime
    "updateTime" : "2020-12-05 09:24:01", // last update time - datetime
    "group" : 3, // associated customer group (id) - int(1…255)
    "collection" : 8, // catalog collection (id) (can be null) - int(1…)
    "collections" : [ 22, 54, … ], // additional collections (id) - int(1…)
    "wishList" : [ 340, 981, 18, … ], // products (id) in the customer's wish list - int(1…)
    "cart" : "RtRi8JWsxK…TMwTA1UJtg", // cart (token) (can be null) - string(32), // saved cart - string(32)
    "invoiceRecipient" : "AB7TR6K", // electronic invoice recipient code or PEC email address - string(0…256)
    "fullName" : "Investigations Inc", // Company name or first and last name - string(1…100)
    "billingAddress" : { // billing address
      "firstName" : "Sherlock", // first name - string(1…25)
      "lastName" : "Holmes", // last name - string(1…25)
      "personalCode" : "SH239IBA", // personal code - string(0…20)
      "companyName" : "Investigations Inc", // company name - string(0…100)
      "companyCode" : "INV8403MC1", // company code number - string(0…20)
      "companyCode2" : "7J BA3 006", // second company code number - string(0…20)
      "street1" : "221b Baker Street", // street, first row - string(1…60)
      "street2" : "", // street, second row - string(0…60)
      "city" : "London", // city - string(1…35)
      "postalCode" : "NW1 6XE", // postal code - string(1…20)
      "stateProv" : "LND", // state, province or county - string(0…3)
      "country" : "GB", // country (ISO code) - string(2)
      "phoneNumber" : "+44+207 2243688", // phone number - string(0…15)
      "mobileNumber" : "", // mobile number - string(0…15)
      "faxNumber" : "", // fax number - string(0…15)
      "email" : "holmes@inv-london.com" // email address - string(3…120)
    },
    "shippingAddress" : { // shipping address (can be null)
      "name" : "John", // recipient name - string(1…100)
      "street1" : "221b Baker Street", // street, first row - string(1…60)
      "street2" : "", // street, second row - string(0…60)
      "city" : "London", // city - string(1…35)
      "postalCode" : "NW1 6XE", // postal code - string(1…20)
      "stateProv" : "LND", // province, state or county - string(0…3)
      "country" : "GB" // country (ISO code) - string(2)
    }
  }
}

customers.authenticate

Authenticates a customer given its email and password and on success returns it.

Request

Admin SDK
Admin.api('commerce.customers.authenticate', request, function(response) { … });

HTTP POST
/api/v13/commerce.customers.authenticate

{
  "email" : "johnsmith@acme.com", // email (required) - string(3…120)
  "password" : "foY5/eLc93Wu5", // password (required) - string(4…16)
  "fields" : [ "id", "code", … ] // fields to return - string
}

Response

{
  "status" : "ok",
  "customer" : { // (can be null)
    "id" : 37091, // identifier - int(1…)
    "code" : "TF78123", // code - string(0…32)
    "canLogin" : true, // indicates if she can login on site - bool
    "hasPassword" : true, // indicates if she has a password - bool
    "encryptedPassword" : "foY5/eLc93Wu5…", // encrypted password - string(45)
    "locale" : "en-GB", // locale (ISO code) of the customer, region is not mandatory - string(2…5)
    "creationTime" : "2020-05-21 16:49:13", // creation time - datetime
    "loginTime" : "2020-12-13 12:05:44", // last login time (can be null) - datetime
    "updateTime" : "2020-12-05 09:24:01", // last update time - datetime
    "group" : 3, // associated customer group (id) - int(1…255)
    "collection" : 8, // catalog collection (id) (can be null) - int(1…)
    "collections" : [ 22, 54, … ], // additional collections (id) - int(1…)
    "wishList" : [ 340, 981, 18, … ], // products (id) in the customer's wish list - int(1…)
    "cart" : "RtRi8JWsxK…TMwTA1UJtg", // cart (token) (can be null) - string(32), // saved cart - string(32)
    "invoiceRecipient" : "AB7TR6K", // electronic invoice recipient code or PEC email address - string(0…256)
    "fullName" : "Investigations Inc", // Company name or first and last name - string(1…100)
    "billingAddress" : { // billing address
      "firstName" : "Sherlock", // first name - string(1…25)
      "lastName" : "Holmes", // last name - string(1…25)
      "personalCode" : "SH239IBA", // personal code - string(0…20)
      "companyName" : "Investigations Inc", // company name - string(0…100)
      "companyCode" : "INV8403MC1", // company code number - string(0…20)
      "companyCode2" : "7J BA3 006", // second company code number - string(0…20)
      "street1" : "221b Baker Street", // street, first row - string(1…60)
      "street2" : "", // street, second row - string(0…60)
      "city" : "London", // city - string(1…35)
      "postalCode" : "NW1 6XE", // postal code - string(1…20)
      "stateProv" : "LND", // state, province or county - string(0…3)
      "country" : "GB", // country (ISO code) - string(2)
      "phoneNumber" : "+44+207 2243688", // phone number - string(0…15)
      "mobileNumber" : "", // mobile number - string(0…15)
      "faxNumber" : "", // fax number - string(0…15)
      "email" : "holmes@inv-london.com" // email address - string(3…120)
    },
    "shippingAddress" : { // shipping address (can be null)
      "name" : "John", // recipient name - string(1…100)
      "street1" : "221b Baker Street", // street, first row - string(1…60)
      "street2" : "", // street, second row - string(0…60)
      "city" : "London", // city - string(1…35)
      "postalCode" : "NW1 6XE", // postal code - string(1…20)
      "stateProv" : "LND", // province, state or county - string(0…3)
      "country" : "GB" // country (ISO code) - string(2)
    }
  }
}

Notes

If you only want to authenticate the customer without returning it, set fields to an empty array []
If authentication succeeds, customer will have the value { …. }; otherwise it will be null
If authentication succeeds, loginTime is updated and the previous login date and time are returned

customers.count

Number of customers that meet the given conditions.

Request

Admin SDK
Admin.api('commerce.customers.count', request, function(response) { … });

HTTP POST
/api/v13/commerce.customers.count

{
  "conditions" : { // counts the customers with this …
    "ids" : [ 70371, 39628, … ], // … with these identifiers - int(1…)
    "code" : "TF78123", // … with this code - string(0…32)
    "canLogin" : true, // … that can login or not on site - bool
    "group" : 3, // … associated with this customer group - int(1…255)
    "email" : "johnsmith@acme.com", // … with this email - string(3…120)
    "personalCode" : "SH239IBA", // … with this personal code - string(1…20)
    "companyCode" : "ACME80193", // … with this company code - string(1…20)
    "keywords" : "acme", // … with these keywords in code, name, personal code, company code or email - string(1…120)
    "country" : "GB", // … with this country - string(2)
    "stateProv" : "LND", // … with this province, state or county - string(1…3)
    "labels" : [ 1, 3, … ], // … with these labels - int(1…32)
    "after" : 70371 // … with identifier after this value - int(0…)
  }
}

Response


{
  "status" : "ok",
  "count" : 67 // number of customers - int(0…)
}

customers.create

Create a new customer.

Request

Admin SDK
Admin.api('commerce.customers.create', request, function(response) { … });

HTTP POST
/api/v13/commerce.customers.create

{
  "customer" : { // customer to create (required)
    "code" : "TF78123", // code - string(0…32)
    "canLogin" : true, // indicates if she can login on site - bool
    "password" : { // password (can be null) :
      "value" : "I9bV2crS", // value - string(6…50)
      "cryptedBy" : "Open2b" // application which has crypted the password (can be null) - string
    },
    "locale" : "en-GB", // locale (ISO code) of the customer, region is not mandatory - string(2…5)
    "creationTime" : "2020-05-21 16:49:13", // creation time - datetime
    "loginTime" : "2020-08-07 10:22:07", // last login time (can be null) - datetime
    "group" : 3, // associated customer group (id) - int(1…255)
    "collection" : 8, // catalog collection (id) (can be null) - int(1…)
    "collections" : [ 22, 54, … ], // additional collections (id) - int(1…)
    "wishList" : [ 340, 981, 18, … ], // products (id) in the wish list - int(1…)
    "invoiceRecipient" : "AB7TR6K", // electronic invoice recipient code or PEC email address - string(0…256)
    "billingAddress" : { // billing address (required)
      "firstName" : "Sherlock", // first name (required) - string(1…25)
      "lastName" : "Holmes", // last name (required) - string(1…25)
      "personalCode" : "SH239IBA", // personal code - string(0…20)
      "companyName" : "Investigations Inc", // company name - string(0…100)
      "companyCode" : "INV8403MC1", // company code number - string(0…20)
      "companyCode2" : "7J BA3 006", // second company code number - string(0…20)
      "street1" : "221b Baker Street", // street, first row (required) - string(1…60)
      "street2" : "", // street, second row - string(0…60)
      "city" : "London", // city  (required) - string(1…35)
      "postalCode" : "NW1 6XE", // postal code (required) - string(1…20)
      "stateProv" : "LND", // state, province or county - string(0…3)
      "country" : "GB", // country (ISO code) (required) - string(2)
      "phoneNumber" : "+44+207 2243688", // phone number - string(0…15)
      "mobileNumber" : "", // mobile number - string(0…15)
      "faxNumber" : "", // fax number - string(0…15)
      "email" : "holmes@inv-london.com" // email address (required) - string(3…120)
    },
    "shippingAddress" : { // shipping address (can be null)
      "name" : "John", // recipient name (required) - string(1…100)
      "street1" : "221b Baker Street", // street, first row (required) - string(1…60)
      "street2" : "", // street, second row - string(0…60)
      "city" : "London", // city (required) - string(1…35)
      "postalCode" : "NW1 6XE", // postal code (required) - string(1…20)
      "stateProv" : "LND", // province, state or county - string(0…3)
      "country" : "GB" // country (ISO code) (required) - string(2)
    }
  }
}

Response

{
  "status" : "ok",
  "id" : 37091 // identifier of the new customer - int(1…)
}

Errors

Field	Type	Description
canLogin	InvalidValue	canLogin can be true only if password is defined
collection	InvalidValue	Collection `<collection>` is not a catalog collection
collection	NotFound	Collection `<collection>` does not exist
collections	InvalidValue	A customer cannot have more than 100 additional collections
collections	InvalidValue	Collection `<collection>` is not an additional collection
collections	Malformed	A collection id is repeated
collections	NotFound	Collection `<collection>` does not exist
creationTime	InvalidValue	Creation time '`<creationTime>`' is in the future
code	AlreadyExists	Code '`<code>`' already exists
email	AlreadyExists	Email '`<email>`' already exists for a customer that can login
email	InvalidValue	'`<email>`' is not a well formed email address
group	NotFound	Customer group `<group>` does not exist
invoiceRecipient	Malformed	'`<invoiceRecipient>`' is not a recipient code or email address
locale	Malformed	'`<locale>`' is not a valid locale code
loginTime	InvalidValue	Login time '`<loginTime>`' is before the creation time
loginTime	InvalidValue	Login time '`<loginTime>`' is in the future
password	Malformed	Password is not a '`<cryptedBy>`' crypted password
password	Malformed	Password must have between 6 and 16 characters
password	Missing	Password is required if customer is active

customers.update

Updates a customer. Any fields left out of the request will remain unchanged.

Request

Admin SDK
Admin.api('commerce.customers.update', request, function(response) { … });

HTTP POST
/api/v13/commerce.customers.update

{
  "id" : 37091, // identifier of the customer to update (required)
  "customer" : { // customer's fields to update (required)
    "code" : "TF78123", // code - string(0…32)
    "canLogin" : true, // indicates if she can login on site - bool
    "password": { // password (can be null):
      "value" : "I9bV2crS", // value - string(6…50)
      "cryptedBy" : "Open2b" // application which has crypted the password (can be null) - string
    },
    "locale" : "en-GB", // locale (ISO code) of the customer, region is not mandatory - string(2…5)
    "creationTime" : "2020-05-21 16:49:13", // creation time - datetime
    "loginTime" : "2020-08-07 10:22:07", // last login time (can be null) - datetime
    "group" : 3, // associated customer group (id) - int(1…255)
    "collection" : 8, // catalog collection (id) (can be null) - int(1…)
    "collections" : [ 22, 54, … ], // additional collections (id) - int(1…)
    "wishList" : [ 340, 981, 18, … ], // products (id) in the wish list - int(1…)
    "cart" : "RtRi8JWsxK…TMwTA1UJtg", // cart (token) (can be null) - string(32), // saved cart - string(32)
    "invoiceRecipient" : "AB7TR6K", // electronic invoice recipient code or PEC email address - string(0…256)
    "billingAddress" : { // billing address
      "firstName" : "Sherlock", // first name (required) - string(1…25)
      "lastName" : "Holmes", // last name (required) - string(1…25)
      "personalCode" : "SH239IBA", // personal code - string(0…20)
      "companyName" : "Investigations Inc", // company name - string(0…100)
      "companyCode" : "INV8403MC1", // company code number - string(0…20)
      "companyCode2" : "7J BA3 006", // second company code number - string(0…20)
      "street1" : "221b Baker Street", // street, first row (required) - string(1…60)
      "street2" : "", // street, second row - string(0…60)
      "city" : "London", // city  (required) - string(1…35)
      "postalCode" : "NW1 6XE", // postal code (required) - string(1…20)
      "stateProv" : "LND", // state, province or county - string(0…3)
      "country" : "GB", // country (ISO code) (required) - string(2)
      "phoneNumber" : "+44+207 2243688", // phone number - string(0…15)
      "mobileNumber" : "", // mobile number - string(0…15)
      "faxNumber" : "", // fax number - string(0…15)
      "email" : "holmes@inv-london.com" // email address (required) - string(3…120)
    },
    "shippingAddress" : { // shipping address (can be null)
      "name" : "John", // recipient name (required) - string(1…100)
      "street1" : "221b Baker Street", // street, first row (required) - string(1…60)
      "street2" : "", // street, second row - string(0…60)
      "city" : "London", // city (required) - string(1…35)
      "postalCode" : "NW1 6XE", // postal code (required) - string(1…20)
      "stateProv" : "LND", // province, state or county - string(0…3)
      "country" : "GB" // country (ISO code) (required) - string(2)
    }
  }
}

Response

{
  "status" : "ok"
}

Errors

Field	Type	Description
canLogin	InvalidValue	canLogin can be true only if password is defined
cart	NotFound	Cart '`<cart>`' does not exist
collection	InvalidValue	Collection `<collection>` is not a catalog collection
collection	NotFound	Collection `<collection>` does not exist
collections	InvalidValue	A customer cannot have more than 100 additional collections
collections	InvalidValue	Collection `<collection>` is not an additional collection
collections	Malformed	A collection id is repeated
collections	NotFound	Collection `<collection>` does not exist
creationTime	InvalidValue	Creation time '`<creationTime>`' is in the future
email	AlreadyExists	Email '`<email>`' already exists for a customer that can login
email	InvalidValue	Email '`<email>`' is not a well formed email address
group	NotFound	Customer group `<group>` does not exist
id	NotFound	Customer '`<id>`' does not exist
invoiceRecipient	Malformed	'`<invoiceRecipient>`' is not a recipient code or email address
locale	Malformed	'`<locale>`' is not a valid locale code
loginTime	InvalidValue	Login time '`<loginTime>`' is before the creation time
loginTime	InvalidValue	Login time '`<loginTime>`' is in the future
password	Malformed	Password is not a '`<cryptedBy>`' crypted password
password	Malformed	Password must have between 6 and 16 characters

customers.delete

Deletes one or more customers.

Request

Admin SDK
Admin.api('commerce.customers.delete', request, function(response) { … });

HTTP POST
/api/v13/commerce.customers.delete

{
  "ids" : [ 37091, 722, 8216, … ] // identifiers of the customers to delete (required) - int(1…)
}

Response

{
  "status" : "ok"
}

Notes

If present, code is unique for each customer
You cannot have two customers with the same email and both with a password assigned
For id values in wishList, the actual existence of products in the catalog is not checked or guaranteed
If password.value is in plain text, then password.cryptedBy must not be set or must be "None". If the password is encrypted, then password.cryptedBy indicates the application used to encrypt it: "Open2b", "osCommerce", "ZenCart" or "CRELoaded"