• Version: 1.2.0

Customers

Customers store information about the people who buy products at your store. They hold their name, email, addresses, and order history. You can assign them to groups, which allow you to provide particular functionality or discounts by groups.

Because customers are flows-based data structures, you can modify the data that they store on the fly. Customer flows have the following fields by default:

Key Type Required Unique Details
id Integer No Yes Automatically populated when you create the customer.
order Array No No Links to this customer’s orders.
created_at String No No Automatically populated when you create the customer.
updated_at String No No Automatically populated when you modify the customer.
first_name String Yes No The customer first name.
last_name String Yes No The customer last name.
email String Yes Yes The email address associated with this customer. This must be unique and can be used to identify the customer when they login.
password String No No A password to save for this customer.
group Integer No No The group to which this customer belongs.
history Array No No An array that contains the number of orders, the value of these orders, and the number of addresses associated with this customer.

Before using customers, you’ll need to create them with the https://api.molt.in/v1/customers endpoint. Once created, customers can be associated with carts. A default cart will be created when you create a customer, which has the same ID number as the customer. You can add addresses to customers using the https://api.molt.in/v1/customers/{ID number}/addresses endpoint, discussed here

Before you can use this (or any endpoint), you need to authenticate to get a bearer token.

This topic will cover the following processes:

Create a New Customer

By default, new stores do not contain any customers, so you will need to create any that you want to use. Every customer that you create must have data for at least the fields marked Required in the table above. You can put data fields in any order.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X POST https://api.molt.in/v1/customers \
  -H "Authorization: Bearer XXXX" \
  -d "first_name=John" \
  -d "last_name=Doe" \
  -d "email=support@moltin.com"

On success, this call will return a 201 Created HTML status code and the customer information for the newly created customer, including any default or generated values. The object it returns looks like this by default (the data will be different, of course):

{
  "status":true,
  "result":
  {
    "id":"1055961503028478872",
    "order":null,
    "created_at":"2015-08-20 19:53:59",
    "updated_at":"2015-08-20 19:53:59",
    "first_name":"John",
    "last_name":"Doe",
    "email":"support@moltin.com",
    "group":null,
    "password":null,
    "history":
    {
      "orders":0,
      "value":"0.00",
      "addresses":0
    }
  }
}

Please note that the password field will never contain the password itself. If there is a password set for this user, this field’s value will be set to true. If you want to authenticate a user, please see the authenticating section.

Retrieve Customer Information

Once you have created one or more customers, you have two methods to retrieve that information. The first requires that you know the ID number of the customer that you want, and it returns solely the information for that one customer. The second returns an array of customers that you can limit by field values, specify a maximum number to return, and offset the start of the array. Using the last two options, you can paginate results by increasing the offset of a search by the previous maximum.

Retrieve a Single Customer by ID

You can GET information for a single customer by appending the ID number to the customers endpoint. No additional data fields are required.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X GET https://api.molt.in/v1/customers/:id \
	-H "Authorization: Bearer XXX"

On success, this returns a 200 OK status code and the customer information for the selected ID number.

Retrieve a List of All Customers

Using the https://api.molt.in/v1/customers endpoint, you can return an array that contains all of the customers that you have created.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X GET https://api.molt.in/v1/customers \
	-H "Authorization: Bearer XXXX"

This will return 200 OK and an array of customer information, as shown in the Create a Customer section. You can pass any customer field values to limit the results, as shown in the next section.

Search for Customers by Field Values

Instead of returning all of your customers, you can only return those that match on specified field values. This lets you do things like return customers based on the email address or number of orders.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X GET https://api.molt.in/v1/customers/search/email=support@moltin.com \
  -H "Authorization: Bearer XXXX"

Again, this will return 200 OK and an array of customer information, even if this call only returns one customer.

You can use multiple data fields to narrow down a search. However, each field must match exactly; otherwise, the search will return all customers.

If you want to return the addresses for a customer, you will need use the addresses endpoint with the customer ID number.

Edit a Customer

To change one or more values for a single customer, use a PUT call with the customers/{ID number} endpoint. You can change most field values through this method, including changing names and email addresses.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X PUT https://api.molt.in/v1/customers/:id \
	-H "Authorization: Bearer XXXX" \
	-d "group=<GROUP ID>"
	-d "group=1061078393216303747" \
	-d "password=supersecret"

This will return 200 OK and the updated customer information.

Grouping Customers

To add customers to groups, you first need to create those groups using the https://api.molt.in/v1/customers/groups endpoint.

curl -X POST https://api.molt.in/v1/customers/groups
	-H "Authorization: Bearer XXXX"
	-d "title=Good People"

The title data field is the only field you can and must set when creating groups. All of the other fields should be familar from other data structures. A successful call will return 201 Created and the following information:

{
	"status":true,
	"result":
	{
		"id":"1061078393216303747",
		"order":null,
		"created_at":"2015-08-27 21:20:20",
		"updated_at":"2015-08-27 21:20:20",
		"title":"Good People"
	}
}

To assign a customer to a group, update their group field with the ID of the new group, as shown in the previous section.

Using Passwords

When you create or update a user, you can optionally set the password for the user. We validate the password supplied and return an error if it does not pass validation. You can edit the password requirement either via Forge > Settings > Password Strength Validation or using a call to the API:

curl -X PUT https://api.molt.in/v1/settings
	-H "Authorization: Bearer XXXX" \
	-d "password_strength_validation=1"

Using one of the following values for password_strength_validation:

Value Strength Requirement
min_6_letters Simple >= 6 alphanumeric characters
min_6_letters_case_diff_numbers Medium >= 6 alphanumeric characters, one uppercase letter and one number
min_8_letters_case_diff_numbers_symbols Complex >= 8 alphanumeric characters, contain at least one uppercase letter, two numbers and one non alphanumeric

By default, the medium strength is used. If the password supplied via you customer POST/PUT call does not pass this validation, the call will fail.

Authenticating a Customer

If you store a password for a customer, you can authenticate them using the https://api.molt.in/v1/customers/token endpoint which takes either a customer id or email in the body to identify the user.

curl -X POST https://api.molt.in/v1/customers/token
	-H "Authorization: Bearer XXXX" \
	-d "email=support@moltin.com" \
	-d "password=supersecret"

OR

curl -X POST https://api.molt.in/v1/customers/token
	-H "Authorization: Bearer XXXX" \
	-d "id=1055961503028478872" \
	-d "password=supersecret"

If the users password matches, we will present the user information in the result:

{
  "status":true,
  "result":
  {
    "id":"1055961503028478872",
    "order":null,
    "created_at":"2015-08-20 19:53:59",
    "updated_at":"2015-08-20 19:53:59",
    "first_name":"John",
    "last_name":"Doe",
    "email":"support@moltin.com",
    "group":null,
    "password":true,
    "history":
    {
      "orders":0,
      "value":"0.00",
      "addresses":0
    }
  }
}

If the user did not authenticate correctly, we will return a status of false with a message

{
  "status": false,
  "message": "The supplied password did not match"
}

If the password did not meet the requirements for security

{
  "status": false,
  "message": "The supplied password did not validate: {requirements}"
}

Delete a Single Customer

To remove a customer, you use the same customers/{ID number} endpoint we used to retrieve a single customer, except we use the DELETE request method.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X DELETE https://api.molt.in/v1/customers/:id
	-H "Authorization: Bearer XXXX"

If successful, this call returns 200 OK and the following:

{
	"status":true,
	"message":"Customer removed successfully"
}

Get a list of customer fields

You can get a list of customer fields like so:

curl -X GET https://api.molt.in/v1/customers/fields
	-H "Authorization: Bearer XXXX"

You can also use this to build a simple form:

$fields = Customer::Fields(null, true);

echo '<form method="customer/create" action="post">';
foreach ( $fields as $field ) {
    echo '<label for="'.$field['slug'].'">'.$field['title'].'</label>';
    echo $field['input'];
}
echo '<button type="submit">Create</button>';
echo '</form>';