Customer

An object representing a customer. The properties below are accessible to administrators. Some of them are also accessible to the logged-in customer.

Properties

Property Description
address Invoice address of the customer. See Address below.
approved Whether the customer is permitted to log in to the shop.
changed Date and time of when the customer was last modified.
created Date and time of when the customer was created.
custom References to any additional details requested by the shop and provided by the customer at checkout, e.g. "desired delivery date", as a list of objects.
deliveryAddress Delivery address of the customer. See DeliveryAddress below.
groups The customer groups in which the customer exists as an array of customer-group objects. Accessible to administrators only.
info An object containing customer information. See Info below.
uid The unique identifier of the customer.

Address

Property Description
address Address line 1 of the customer.
address2 Address line 2 of the customer.
country Country of the customer as an ISO 3166-1 alpha-2 code, e.g. "SE" (Sweden).
firstName First name of the customer.
lastName Last name of the customer.
phoneDay Daytime phone number of the customer.
phoneMobile Mobile phone number of the customer.
phoneNight Evening phone number of the customer.
postcode Postcode / ZIP code of the customer.
state State or province of the customer as a two-letter code, e.g. "AL" (Alabama), if any.
town Post town of the customer.

DeliveryAddress

Property Description
address Address line 1 of the customer.
address2 Address line 2 of the customer.
country Country of the customer as an ISO 3166-1 alpha-2 code, e.g. "SE" (Sweden).
copyAddress Whether delivery address is copied from the invoice address.
name First name and last name of the customer.
postcode Postcode / ZIP code of the customer.
state State or province of the customer as a two-letter code, e.g. "AL" (Alabama), if any.
town Post town of the customer.

Info

Property Description
customerNumber An optional identifier of the customer modifiable by an adminstrator. May contain letters, hyphens, numbers and other characters.
email Email address of the customer.
newsletter Whether the customer shall receive newsletters from the shop.
nin National identification number (or equivalent) or organization number (or equivalent) of the customer.
notes Shop's note of the customer, e.g. "Life-time guarantee on all items". Accessible to administrators only.
type Customer type: "business" or "individual".
username Username of the customer.
vatNumber Value-added tax number of the customer.

Methods

changePassword

Changes the password for a logged-in customer. This method will update a customer's password if given the correct old password and a valid new password. All subsequent logins will be required to use the new password.

Parameters

Parameter Description
oldpassword The old password.
newpassword The new password.

Returns

Response
null

Errors

Code Message Description
3004 Invalid password The new password is invalid.
Invalid login The old password is invalid.
Forbidden The customer is not logged in.

Example

API Console
Customer.changePassword("foobarpass", "barfoopass")
Response
null

confirmSignup

Confirms a membership. The customer needs to run signup beforehand to obtain both the hash and the activation code sent to their email address. After a successful request to this method, the new customer can use login to access their account.

Parameters

Parameter Description
email The email address to which the activation code was sent.
hash The hash as returned by signup.
code The activation code included in the confirmation email.

Returns

Response
null

Errors

Code Message Description
3003 Bad signup code The activation code included in the email is invalid.
3006 Confirmation failed The confirmation failed because there is no pending customer with the given email.

Example

API Console
Customer.confirmSignup("foobar@example.com", "7037807198c22a7d2b0807371d763779a84fdfcf", "03d302c9a24f67de")
Response
null

count

Takes a filter object and returns the number of customers found, as an integer.

Parameters

A filter object specifying which customers to count. See Filter objects on the page List selection.

Example

The request below returns the number of customers created since 1 January 2014.

API Console
Customer.count(
  {
    "/created": {
      "min":"2014-01-01T00:00:00Z"
    }
  }
)
Response
999

create

Creates a new customer. This is shorthand for set with uid null.

Parameters

Parameter Description
patch An object containing the properties and values to set for the new customer.
query A query specifying what to return after a successful create (optional).

get

Fetches information about a customer.

Parameters

Parameter Description
uid The unique identifier of a customer.
query Which info to return. See Query language.

Example

API Console
Customer.get(123456, ["uid", "groups", "address"])
Response
{
  "uid": 123456,
  "groups": [12345,12346],
  "address": {
    "firstName": "Sven",
    "lastName": "Svensson",
    "address": "Example street 9",
    "postcode": "12345",
    "town": "Example town",
    "country": "SE"
  }
}

getSchema

Parameters

The unique identifier of an existing customer or null for a new customer.

Example

Request:

API Console
Customer.getSchema(123456)
Response
{
  "uid": {
    "type":        "integer",
    "description": "Customer instance UID."
  },
  "groups": {
    "type": "array",
    "description": "List of customer group memberships.",
    "items": {
      "type": "integer",
      "description": "Customergroup UID."
    }
  }
  "address": {
    "type": "object",
    "description": "Customer's main address.",
    "properties": {
      "company": {
        "title":       "Business name",
        "type":        "string",
        "description": "business name."
      },
      "firstName": {
        "title":       "First name",
        "type":        "string",
        "description": "Customer first name."
      },
      "lastName": {
        "title":       "Last name",
        "type":        "string",
        "description": "Customer last name."
      },
      "address": {
        "title":       "Address line 1",
        "type":        "string",
        "description": "Customer address, such as street and number."
      },
      "address2": {
        "title":       "Address line 2",
        "type":        "string",
        "description": "Customer address second line."
      },
      "postcode": {
        "title":       "Postcode",
        "type":        "string",
        "description": "Customer postcode."
      },
      "town": {
        "title":       "Town",
        "type":        "string",
        "description": "Customer town."
      },
      "state": {
        "title":       "State/province",
        "type":        "string",
        "description": "State or province, e.g. 'AL' (Alabama)."
      },
      "country": {
        "title":       "Country"
        "type":        "string",
        "description": "Customer country as two-letter ISO 3166-1 alpha-2, e.g. 'SE'."
      },
      "phoneDay":
        "title":       "Phone daytime",
        "type":        "string",
        "description": "Customer telephone number during daytime."
      },
      "phoneNight": {
        "title":       "Phone evening",
        "type":        "string",
        "description": "Customer telephone number during evenings."
      },
      "phoneMobile": {
        "title":       "Mobile-phone"
        "type":        "string",
        "description": "Customer mobile-phone number."
      }
  },
  "deliveryAddress": {
    "type":        "object",
    "description": "A deliveryAddress with data populated. Read-only if shop has deactivated delivery address.",
    "properties": {
      "copyAddress": {
        "type":        "boolean",
        "description": "When true, deliveryAddress will automatically contain the same data as corresponding fields in the address object."
      },
      "name": {
        "title":        "Name",
        "type":         "string",
        "descritption": "Delivery address first and lastname."
      },
      "address": {
        "title":       "Address line 1",
        "type":        "string",
        "description": "Delivery address. Street or c/o."
      },
      "address2": {
        "title":       "Address line 2"
        "type":        "string",
        "description": "Delivery address second line."
      },
      "postcode": {
        "title":       "Postcode"
        "type":        "string",
        "description": "Delivery postcode."
      },
      "town": {
        "title":       "Town",
        "type":        "string",
        "description": "Delivery town."
      },
      "state": {
        "title":       "State/province"
        "type":        "string",
        "description": "State or province."
      },
      "country": {
        "title":       "Country"
        "type":        "string",
        "description": "Delivery country as two-letter ISO 3166-1 alpha-2."
      }
    }
  },
  "custom": {
    "description": "Shop's custom fields",
    "type": "object",
    "properties": {
      "123456": { //This is an example of a custom field.
        "type":  "string",
        "title": "Field 1"
      }
    }
  },
  "info": {
    "type": "object",
    "description": "Generic customer information.",
    "properties": {
      "type": {
        "title": "Customer type",
        "type": "string",
        "description": "Customer type: business or individual.",
        "enum": [
          "business",
          "individual"
        ]
      },
      "nin": {
        "title":       "National identification number",
        "type":        "string",
        "description": "National identification number (or equivalent) applicable in customer country."
      },
      "email": {
        "title":       "Email",
        "type":        "string",
        "description": "Customer email address.",
        "format":      "email"
      },
      "vatNumber": {
        "title":       "VAT number",
        "type":        "string",
        "description": "VAT number."
      },
      "customerNumber": {
        "title":       "Customer number",
        "type":        "string",
        "description": "Customer number assigned by the shop.",
      },
      "newsletter": {
        "title":       "Newsletter",
        "type":        "boolean",
        "description": "Newsletter active for customer."
      },
      "note": {
        "title":       "Admin note",
        "type":        "string",
        "description": "Shop note of the customer."
      }
    }
  }
}

list

Returns an array of objects representing customers.

Parameters

Parameter Description
query A query object specifying what to fetch from each customer. This is the same as for get. See Query language.
selection A list-selection object specifying which customers to fetch. See List selection.

These orderings are available:

  • uid
  • approved
  • changed
  • company
  • created
  • customerNumber
  • email
  • firstName
  • lastName

Example

The following request returns the company name, email and unique identifier of all the customers created since 1 January 2014, sorted by company:

API Console
Customer.list({"info":{"email":true}, "address":{"company":true}, "uid":true}, {"filters":{"/created":{"min":"2014-01-01T00:00:00Z"}},"sort":"company"})
Response
[
  {
    "address": {
      "company": "Elisabeth Consulting"
    },
    "info": {
      "email": "elisabeth@example.com"
    },
    "uid": 9876543
  },
  {
    "address": {
      "company": "Libre Software Inc."
    },
    "info": {
      "email": "libre@example.com"
    },
    "uid": 9876540
  }
]

login

Logs in a customer to the shop. A session is needed before login can be attempted.

Parameters

Parameter Description
username Username for the customer account.
password Password for the customer account.
query A query specifying what to return after a successful login (optional).

Errors

Code Message Description
3001 Login failure If either the username or password is incorrect.
1008 Session missing If no session is supplied in the context.

Returns

If the login is successful, the return value will be an empty object. If a query is provided, however, then the return value will be an object with properties specified in the query.

Example

API Console
Customer.login("foo", "foobarpass")
Response
{}

With a query:

API Console
Customer.login("foo", "foobarpass", "uid")
Response
{
  "uid": 123456
}

logout

Logs out the customer. A session is required for logging out. If no user is logged in when calling this method, then nothing will happen.

Errors

Code Message Description
1008 Session missing If no session is supplied in the context.

newsletterSubscribe

Subscribes a customer to the shop's newsletter.

Parameters

The email address of the customer, as a string. Or first name, last name and email address of the customer as strings.

Returns

If the request is successful, then the return value will be null.

Example

API Console
newsletterSubscribe("Foo", "Bar", "email@example.com")
Response
null

newsletterUnSubscribe

Unsubscribes a customer from the shop's newsletter.

Parameters

The email address of the customer, as a string.

Returns

If the request is successful, the return value will be null.

Errors

Code Message Description
1006 Forbidden The request is forbidden. To proceed, you need to either log in or use a persistent authentication token.

Example

API Console
newsletterUnsubscribe("email@example.com")
Response
null

normalize

Fetches a normalized version of the patch. Uses the same parameters as set and validate. While set also normalizes the patch, before storing, normalize only returns the normalized patch. For all properties with number types, integers or floating-point values in strings are converted to number literals. A normalization error is thrown when we are unable to convert a string to a number literal.

Parameters

Parameter Description
uid The unique identifier of an article or null to create a new customer.
patch An object containing the properties and values to normalize.

Example

API Console
Customer.normalize(123456, {"groups": ["1"]})
Response
{
  "uid": 123456,
  "groups" : [1]
}

requestPasswordReset

Requests a password reset for a customer. This method will return a hash and send an email to the customer containing a reset code. These two values can then be used to reset the customer's password using resetPassword.

Parameters

The username or email of the customer.

Returns

The hash to use with the reset code.

Example

API Console
Customer.requestPasswordReset("foobar@example.com")
Response
"ab7911513debc7015ad50429a8159771458b24ce"

resetPassword

Resets the password. The customer needs to run requestPasswordReset beforehand to obtain both the hash and the reset code sent to their email address. After a successful reset, the customer should be able to use login with their new password.

Parameters

Parameter Description
username The username of the customer.
hash The hash as returned by requestPasswordReset.
code The reset code as sent to the customer's email address.
newpassword The customer's new password.

Errors

Code Message Description
3002 Bad reset code The reset code provided is invalid.

Returns

Response
null

Example

API Console
Customer.resetPassword("foo", "ab7911513debc7015ad50429a8159771458b24ce", "99875c5ebd8a35ae", "barfoopass")
Response
null

set

Creates or updates a customer.

If a customer is created who has recently started to sign up but not yet used confirmSignup, then the pending customer will be deleted and any request to confirmSignup on that customer will fail.

Parameters

Parameter Description
uid The unique identifier of a customer or null to create a new customer.
patch An object containing the properties and values to set for the customer.
query A query specifying what to return after a successful set (optional).

Example

The following request updates the email-address record for the customer with the unique identifier 9876543 and returns the email, company name and unique identifier.

API Console
Customer.set(9876540, {"info": {"email": "libre.software@example.com"}}, {"uid": true}, "address":{"company": true}])
Response
{
  {
    "address": {
      "company": "Libre Software Inc.",
    },
    "info": {
      "email": "libre.software@example.com"
    },
    "uid": 9876540
  }
}

validate

Validates the data to be set. The performed validation is the same as in set; it validates the resulting object and includes all the required properties. However, nothing is saved.

Parameters

Parameter Description
uid The unique identifier of an existing customer or null.
patch An object containing the properties and values to set before validating.

Returns

An array of validation-error objects, each containing the keys pointer (a property referenced using a JSON Pointer) and message (a readable text in the language of the context). An empty array is returned if there are no validation errors.

delete

Permanently delete a customer.

Parameters

Parameter Description
uid The unique identifier of a customer.
API Console
Customer.delete(9876540)
Response
{ }