Customer resource

Pulling & pushing customer data is common use of the API. This section documents the Customer resource & a few other related resources.

The Customer resource (note: singular) stores all data relating to a customer / member of the website. Other related resources include:

• UserCustomerGroups - the relationship record between a Customer and a UserGroups resource, containing the group code(s) that this customer is in.
  • UserGroups - data about the actual groups - related to the UserCustomerGroups relationship record.
• Order - any orders related to the customer

Customer fields

The main customer fields you may want to interact with include:

• username - the primary key for a customer.
• password - a password hash for the customer
• email - email address
• phone_day - the main phone number
• phone_night - alternative phone number
• Primary (billing) customer data / address fields:
  • b_company - company name
  • b_fname - first name
  • b_lname - last name
  • b_address1 - address 1
  • b_address2 - address 2
  • b_address3 - address 3
  • b_city - city
  • b_state - state
  • b_zip - postcode
  • b_country - country code
• Shipping customer data / address fields (if different):
  • company - company name
  • fname - first name
  • lname - last name
  • address1 - address 1
  • address2 - address 2
  • address3 - address 3
  • city - city
  • state - state
  • zip - postcode
  • country - country code
• inactive - is this customer inactive?
• discount - an adhoc % discount to apply to this customer. This is an int, so 20 is a 20% discount.
• no_email - has this user unsubscribed from all unsolicited communications?
• mv_shipmode - preferred shipping mode (as per the Shipping resource)
• custom_data1 to custom_data4 - these are blank fields that are not used by our software, and exist for 3rd party developers needing to store additional adhoc data against a customer. Feel free to use them - just be sure they're not being used by another integration.

Example - creating a customer

The following request could be used to create a new customer (or update an exising customer if one already existed with the same username). We can set the new customer's groups at the same time by POSTing to the appropriate resource specification.

POST /API/V3/Customer+UserCustomerGroups
<ResultSet>
    <Customer>
        <username>peter@parker.nz</username>
        <password>PETERFOO123</password>
        <email>peter@parker.nz</email>
        <b_fname>Peter</b_fname>
        <b_lname>Parker</b_lname>
        <UserCustomerGroup>
            <username>peter@parker.nz</username>
            <group_code>dealer</group_code>
        </UserCustomerGroup>
        <UserCustomerGroup>
            <username>peter@parker.nz</username>
            <group_code>vip</group_code>
        </UserCustomerGroup>
    </Customer>
</ResultSet>

The password will be automatically hashed before storing in the database. Future GETs will return the hashed password.

You could look to update a customer's password by using a PUT as follows:

PUT /API/V3/Customer/peter@parker.nz
<ResultSet>
    <Customer>
        <username>peter@parker.nz</username>
        <b_fname>Paul</b_fname>
    </Customer>
</ResultSet>

Example - Creating a customer group

Note you only have to include the entry key and the fields you wish to update.

If you need to dynamically create customer groups, you can POST to the UserGroups resource:

POST /API/V3/UserGroups
<ResultSet>
    <UserGroup>
        <code>jedis</code>
        <title>Jedis</title>
    </UserGroup>
    <UserGroup>
        <code>storm-troopers</code>
        <title>Storm Troopers</title>
    </UserGroup>
</ResultSet>

Integrations occasionally use this approach to create a customer group for each customer in order to implement customer specific pricing (be careful that you don't have too many customers / products if implementing this or the number of entries can explode very quickly, resuting in pages with lots of price calculations slowing right down).

Related resources

UserCustomerGroups 1:M

When a Customer has been assigned to one or more customer groups, this resource will represent the relationship between the customer and the group. If you join it into your resource specification - e.g. /API/V3/Customer+UserCustomerGroups, it will embed a node for this resource for each group the customer is in.

Each node will contain these fields:

• code - primary key (auto increment integer)
• username - the customer username
• group_code - the code from the related UserGroups resource
• subscribed - is the customer subscribed to this group for unsolicited communication (true), or have they unsubscribed from this specific group unsubscribed.
• custom_data1 to custom_data4 - these are blank fields that are not used by our software, and exist for 3rd party developers needing to store additional adhoc data against this record. Feel free to use them - just be sure they're not being used by another integration.

UserGroups 1:M

Not related directly to a customer - but to the UserCustomerGroups entry (allowing a many:many relationship between Customer & UserGroups). If you need additional data about the group (e.g. its title) you can join the UserGroups resource to the UserCustomerGroups entry. In a resource specification this may look like: /API/V3/Customer+(UserCustomerGroups+UserGroups).

Key fields include:

• code - the customer group code
• title - name / title of the group
• description - group description
• subscribable - should a customer be able to opt-in or opt-out from this group? If so it should be public. If this group is for internal grouping only, set it to private.
• subscribe_text - if this is a public group, what text should be displayed to try get the customer to subscribe to this group?
• parent_code - optionally make this a 'sub-group' underneath another parent group by specifying the UserGroup code for its parent.

Order 1:M

Order(s) that have been placed by the Customer.

See more in the Order resource documentation.