Abicart API

# Customer

An object representing a customer.

info

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

info

Please note that the unique identifier is not the same as the customer number.

# Properties

Property Type Description
uid integer The unique identifier of the customer.
changed string Date and time of when the customer was last modified.
approved boolean Whether the customer is permitted to log in to the shop.
created string Date and time of when the customer was created.
language string Preferred language for the customer.
groups array The customer groups in which the customer exists as an array of Customergroup objects. Accessible to administrators only.
address Address Invoice address of the customer. See Address below.
deliveryAddress DeliveryAddress Delivery address of the customer. See DeliveryAddress below.
custom object 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.
info Info An object containing customer information. See Info below.

# Address

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

# DeliveryAddress

Property Type Description
copyAddress boolean Whether delivery address is copied from the address.
company string Delivery company name, if any.
name string Delivery first name and last name
address string Delivery address line 1.
address2 string Delivery address line 2
postcode string Delivery postcode / ZIP code
town string Delivery city/town
country string Delivery countryas an ISO 3166-1 alpha-2 code, e.g. "SE" (Sweden).
state string Delivery state or province as a two-letter code, e.g. "AL" (Alabama), if any.
phone string Delivery phone number

# Info

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

# 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.

# 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

Customer.changePassword("foobarpass", "barfoopass")

# 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.

# 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

Customer.confirmSignup("foobar@example.com", "7037807198c22a7d2b0807371d763779a84fdfcf", "03d302c9a24f67de")

# 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 2019.

Customer.count({
  "/created": {
    "min": "2019-01-01T00:00:00Z"
  }
})

# 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). See Query language.

# delete

Permanently delete a customer.

# Parameters

Parameter Description
uid The unique identifier of a customer.

# Example

Customer.delete(9876540)

# 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

Customer.get(123456, [
  "uid",
  "groups",
  "address"
])

# getSchema

Fetches the JSON Schema which can be used for client-side validation.

# Parameters

The unique identifier of an existing customer or null for a new 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 2019, sorted by company:

Customer.list({
  "uid": true,
  "info": {
    "email": true
  },
  "address": {
    "company": true
  }
}, {
  "filters": {
    "/created": {
      "min": "2019-01-01T00:00:00Z"
    }
  },
  "sort": "company"
})

# 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). See Query language.

# 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

Customer.login("foo", "foobarpass")

With a query:

Customer.login("foo", "foobarpass", [
  "uid"
])

# 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.

# Example

Customer.logout()

# newsletterSubscribe

Subscribes a customer to the webshop'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.

# Example

Customer.newsletterSubscribe("email@example.com")

With first name and last name:

Customer.newsletterSubscribe("Foo", "Bar", "email@example.com")

# newsletterUnSubscribe

Unsubscribes a customer from the webshop'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

Customer.newsletterUnsubscribe("email@example.com")

# 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 a customer or null to create a new customer.
patch An object containing the properties and values to normalize.

# Example

Customer.normalize(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

Customer.requestPasswordReset("foobar@example.com")

# 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

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

# Example

Customer.resetPassword("foo", "ab7911513debc7015ad50429a8159771458b24ce", "99875c5ebd8a35ae", "barfoopass")

# set

Creates or updates a customer.

info

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). See Query language.

# 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.

Customer.set(9876543, {
  "info": {
    "email": "libre.software@example.com"
  }
}, {
  "uid": true,
  "info": {
    "email": true
  },
  "address": {
    "company": true
  }
})

# 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.