TS Commerce Developers

Customers API

Current version: v1.1 beta
Last Update: 2023/04/20

Customers are users (registered or not) who have interacted with your store, making orders or registering.

Customers List

GET
/clients/list.json
PARAMETERS LIST
created_at_from (unix timestamp) Return all customers where customer creation date is greater than {timestamp}. Must be used with created_at_to
created_at_to (unix timestamp) Return all customers where customer creation date is lower than {timestamp}.Must be used with created_at_from
updated_at_from (unix timestamp) Return all customers where customer update date is greater than {timestamp}.Must be used with updated_at_to
updated_at_to (unix timestamp) Return all customers where customer update date is lower than {timestamp}.Must be used with updated_at_from
nodes (string) Return available entity node, separated by ',': eg: nodes=custom_fields,fullname,accountTypem group
Accepted values: custom_fields, fullname, accountType group
account node is available only on /clients/list_paginated.json and has a leaky bucket restriction
accountType (string) Filter customers based on account type. Accepted values: guest, registered
List customers Request

$storeden = new Storeden\Storeden($config);
$customers_list = $storeden->get('/clients/list.json?nodes=fullname,accountType');
List customers Response

[
	{
		"id": "5b49a6a4deddac755c8cee7a",
		"fullname": "John Smith",
		"last_name": "Smith",
		"first_name": "John",
		"email": "john-smith@domain.tld",
		"created_at": "2018-07-14T09:28:52+02:00",
		"updated_at": null,
		"userUID": 0,
		"accept_marketing": false,
		"accountType": "guest"
	},
	...
]

Get Customer Details

View all information about a specified customer

GET
/clients/client.json?id={customer-id}
PARAMETERS LIST
id required* (StoredenId) Unique id of customer.
email required* (string) Email of your customer.
* one of this fields required
Get customers Request

$storeden = new Storeden\Storeden($config);
$customer_data = $storeden->get('/clients/client.json?id=5b49a6a4deddac755c8cee7a');

/** OR **/

$storeden = new Storeden\Storeden($config);
$customer_data = $storeden->get('/clients/client.json?email=john.smith@domain.tld');
Get customers Response

{
    "fullname": "John Smith",
    "website": "https://domain.com",
    "email": "john.smith@domain.tld",
    "phone": "+1 007 007 007",
    "mobile": "+10 07 007 007",
    "address": "3411 Las Vegas Blvd. South",
    "city": "Las Vegas",
    "zip": "NV89109",
    "state": "Nevada",
    "country": "254",
    "code": "",
    "userUID": 120007,
    "id": "5b49a6a4deddac755c8cee7a",
	"accountType": "registered"
}

Add a new customer

POST
/clients/client.json
PARAMETERS LIST
fullname required * (string) Required if both first_name and last_name are empty
first_name required * (string) Required if fullname is empty
last_name required * (string) Required if fullname is empty
email required (string) If already exists in your customer database will throw an error
website (string)
phone (string)
mobile (string)
address (string) Full address included apt number
city (string)
zip (string) Specify a valid postal code. Will be validated against country postal code rules
country (string) A valid country name legacy
state (string) Specify a valid state namelegacy
tax_number (string)
countryUID (int) Refer to Countries API
stateUID (int) Refer to Countries API
metadata (associative array) Sub values:
sdi: Italia Digitial Invoice code
pec: Italian Certified Email address
note (string) April 24th, 2019 Custom Text for customer's data
Create customer Request

$storeden = new Storeden\Storeden($config);

$customer_data = array();
$customer_data['fullname'] = 'John Smith';
$customer_data['email'] = 'john.smith@domain.tld';
// etc..

$result = $storeden->post('/clients/client.json', $customer_data);
Create customer Response

{
    "client": {
        "id": "569d08bb16f46ac71e7b23c6"
    }
}

Update customer data

PUT
/clients/client.json
PARAMETERS LIST
id required (StoredenID)
fullname required * (string) Required if both first_name and last_name are empty
first_name required * (string) Required if fullname is empty
last_name required * (string) Required if fullname is empty
phone (string)
address (string) Full address included apt number
city (string)
zip (string) Specify a valid postal code. Will be validated against country postal code rules
region (string) State/Region legacy
state (string) Country name legacy
tax_number (string)
countryUID (int) Refer to Countries API
stateUID (int) Refer to Countries API
note (string) April 24th, 2019 Custom Text for customer's data
Update Customer Request

$storeden = new Storeden\Storeden($config);

$customer_data = array();
$customer_data['id'] = '569d08bb16f46ac71e7b23c6';
$customer_data['note'] = 'Customer description';
$customer_data['fullname'] = 'John Smith';
// etc..

$result = $storeden->put('/clients/client.json', $customer_data);
Update Customer Response

{
    "ok": 1,
    "nModified": 1,
    "n": 1,
    "err": null,
    "updatedExisting": true
}

Remove customer from list

Permanently delete customer from your customers list.

DELETE
/clients/client.json
PARAMETERS LIST
id required (string)
Remove customer Request

$storeden = new Storeden\Storeden($config);
$result = $storeden->delete('/clients/client.json', ['id' => '569d08bb16f46ac71e7b23c6']);
Remove customer Response

{
    "ok": 1,
    "err": null,
}

Assign customer to a group

PUT
/clients/client2group.json
PARAMETERS LIST
id required (StoredenID) Unique id of a specific customer
group_id required (StoredenID|null) Unique id of a customers group
Assign customer to group Request

$storeden = new Storeden\Storeden($config);
$result = $storeden->put('/clients/client2group.json', ['id' => '569d08bb16f46ac71e7b23c6', 'group_id' => '59fb00b016f46afa7d0031da']);
Assign customer to group Response

{
    "id": "569d08bb16f46ac71e7b23c6",
    "group": {
        "before": "",
        "after": "59fb00b016f46afa7d0031da"
    }
}

Remove customer from a group

DELETE
/clients/client2group.json
PARAMETERS LIST
id required (StoredenID) Unique id of a specific customer
Remove customer from a group Request

$storeden = new Storeden\Storeden($config);
$result = $storeden->delete('/clients/client2group.json', ['id' => '569d08bb16f46ac71e7b23c6']);
Remove customer from a group Response

{
    "id": "569d08bb16f46ac71e7b23c6",
    "group": {
        "before": "59fb00b016f46afa7d0031da",
        "after": null
    }
}

Update customer tags

This API replaces all customer tags with the submitted tags.

POST
/clients/tags.json
PARAMETERS LIST
id required* (StoredenID) Unique id of a specific customer
email required* (string) Customer email
tags required (string) a list of tags separated by ","
* one of "id" or "email" is required. If passed both, will be used the "id"
Overwrite customer tag Request

$storeden = new Storeden\Storeden($config);
$result = $storeden->post('/clients/tags.json', ['id' => '569d08bb16f46ac71e7b23c6', 'tags' => 'test_tag_3,test_tag1']);
Overwrite customer tag Response

{
    "ok": 1,
    "nModified": 1,
    "n": 1,
    "err": null,
}

Add tags to customer

Previous tag to customer will be keeped and applied only the specified tags that are not assigned to customer 

PUT
/clients/tags.json
PARAMETERS LIST
id required* (StoredenID) Unique id of a specific customer
email required* (string) Customer email
tags required (string) a list of tags separated by ","
* one of "id" or "email" is required. If passed both, will be used the "id"
Add customer tag Request

$storeden = new Storeden\Storeden($config);
$result = $storeden->put('/clients/tags.json', ['id' => '569d08bb16f46ac71e7b23c6', 'tags' => 'test_tag_3,test_tag5,test_tag1']);
Add customer tag Response

{
    "ok": 1,
    "nModified": 1,
    "n": 1,
    "err": null,
}

Remove tags to customer

DELETE
/clients/tags.json
PARAMETERS LIST
id required* (StoredenID) Unique id of a specific customer
email required* (string) Customer email
tags required (string) a list of tags separated by ","
* one of "id" or "email" is required. If passed both, will be used the "id"
Remove customer tag Request

$storeden = new Storeden\Storeden($config);
$result = $storeden->delete('/clients/tags.json', ['id' => '569d08bb16f46ac71e7b23c6', 'tags' => 'test_tag5,test_tag1']);
Remove customer tag Response

{
    "ok": 1,
    "nModified": 1,
    "n": 1,
    "err": null,
}

Batch add tags to customers list

PUT
/clients/batchTags.json
PARAMETERS LIST
email[] required* (string) Insert one "email[]=email_address" for each customer you want to update
tags required (string) a list of tags separated by ","
* if you want to update all customers, use email=*
Batch add tags to customers list Request

$storeden = new Storeden\Storeden($config);
$result = $storeden->put('/clients/batchTags.json', ['email' => '*', 'tags' => 'new_tag_1']);
Batch add tags to customers list Response

{
    "ok": 1,
    "nModified": 19248,
    "n": 1,
    "err": null,
}

Batch update tags to customers list

This API replaces all customer tags with the submitted tags.

POST
/clients/batchTags.json
PARAMETERS LIST
email[] required* (string) Insert one "email[]=email_address" for each customer you want to update
tags required (string) a list of tags separated by ","
* if you want to update all customers, use email=*
Batch update tags to customers list Request

$storeden = new Storeden\Storeden($config);
$result = $storeden->post('/clients/batchTags.json', ['email' => '*', 'tags' => 'new_tag_2']);
Batch update tags to customers list Response

{
    "ok": 1,
    "nModified": 19248,
    "n": 1,
    "err": null,
}

Batch remove tag to customers list

DELETE
/clients/batchTags.json
PARAMETERS LIST
email[] required* (string) Insert one "email[]=email_address" for each customer you want to update
tag required (string) specify a single tag to remove, you can use wildcard like: test_tag* to remove all tags starting with test_tag
* if you want to update all customers, use email=*
Batch remove tag to customers list Request

$storeden = new Storeden\Storeden($config);
$result = $storeden->delete('/clients/batchTags.json', ['email' => '*', 'tag' => 'new_tag*']);
Batch remove tag to customers list Response

{
    "ok": 1,
    "nModified": 19248,
    "n": 1,
    "err": null,
}

Update customer accept marketing field

PUT
/clients/accept_marketing.json
PARAMETERS LIST
id required* (StoredenID) Customer Entity ID
accept_marketing required (enum) specify "true" for enable this field, "false" to disable this field. All changes are logged.
Update customer accept marketing field Request

$storeden = new Storeden\Storeden($config);
$result = $storeden->put('/clients/accept_marketing.json', ['id' => '569d08bb16f46ac71e7b23c6', 'accept_marketing' => 'true']);
Update customer accept marketing field Response

{
    "ok": 1,
    "nModified": 1,
    "n": 1,
    "err": null,
    "errmsg": null,
    "updatedExisting": true,
    "message": "Field changed"
}

Update Customer custom fields

Update custom fields of customer entity. Can be used with 3rd party apps

Preview Release 

PUT
/clients/custom_fields.json
PARAMETERS LIST
id required* (StoredenID) Customer Entity ID
custom_fields required (mixed) Associative array of fields to merge with current fields on customer. Send empty value to reset a single fields.
Update Customer custom fields Request

$storeden = new Storeden\Storeden($config);

$payload = array();
$payload['id'] = '569d08bb16f46ac71e7b23c6';
$payload['custom_fields'] = array(
	'external_id' => 6,
	'external_email' => 'test@provider.lan'
);

$result = $storeden->put('/clients/custom_fields.json', $payload);
Update Customer custom fields Response

{
    "ok": 1,
    "nModified": 1,
    "n": 1,
    "err": null,
    "errmsg": null,
    "updatedExisting": true,
}