Customer Management

1. Customer Lists

Like catalogs, customer lists exist at either location or account level.

Name unicity is ruled by the same constraints as catalogs: at the location level, they are uniquely identified by their name. And an account level customer list cannot have the same name as another account or location level customer list.

1.1. Retrieve Customer List

Returns a customer list.

Endpoint:
GET /customer_lists/:customer_list_id
Access level:
location, account

Example request:

GET /customer_lists/ag8u4

{ "id": "ag8u4", "name": "Online customers"}

1.2. List Customer Lists

Returns a location's Customer Lists. Includes location and account level Customer Lists.

Endpoint:
GET /locations/:location_id/customer_lists
Short endpoint:
GET /location/customer_lists (location only)
Access level:
location, account

Account level Customer Lists of an account:

Endpoint:
GET /accounts/:account_id/customer_lists
Short endpoint:
GET /account/customer_lists (account only)
Access level:
account

Example request:

GET /locations/3r4s3-1/customer_lists

[ { "id": "apm3s", "name": "Online customers", "created_at": "2017-06-25T11:43:51Z" }, { "id": "s7ma5", "name": "POS customers", "created_at": "2017-05-19T13:23:10Z" }]

1.3. Create Customer List

Creates a new customer list.

To create a location-level customer list, use this request:

Endpoint:
POST /locations/:location_id/customer_lists
Short endpoint:
POST /location/customer_lists (location only)
Access level:
location, account

To create an account-level customer list:

Endpoint:
POST /accounts/:account_id/customer_lists
Short endpoint:
POST /account/customer_lists (account only)
Access level:
account

Request parameters:

NameTypeDescription
namestringThe name of the customer list.

Example request:

POST /locations/3r4s3-1/customer_lists

{ "name": "Web customers"}

If a customer list with the same name already exists, it returns an error.

1.4. Update Customer List

Update a customer list.

Endpoint:
PUT /customer_lists/:id
Access level:
location, account

Example request:

PUT /customer_lists/apm3s

{ "name": "New customers"}

If name is used by another customer list, it returns an error.

1.5. Delete Customer List

Delete a customer list and its customers.

Endpoint:
DELETE /customer_lists/:id
Access level:
location, account

Example request:

DELETE /customer_lists/apm3s

2. Customers

2.1. Retrieve Customer

Returns a customer's details.

Endpoint:
GET /customer_lists/:customer_list_id/customers/:customer_id
Access level:
location, account

Example request:

GET /customer_lists/smpse3/customers/jdj9v

{ "id": "jdj9v", "email": "xxx@yyy.com", "first_name": "Jimmy", "last_name": "Watson", "gender": "male", "birth_date": null, "company_name": null, "phone": "+44.123456789", "address_1": "1 Town Road", "address_2": null, "postal_code": "N9 0HL", "city": "London", "state": null, "country": "GB", "latitude": 45.7571206, "longitude": 4.8307575, "delivery_notes": null, "sms_marketing": true, "email_marketing": true, "nb_orders": 2, "order_total": "28.40 GBP", "first_order_date": "2017-01-18T17:15:11+01:00", "last_order_date": "2017-01-23T10:13:21+01:00", "loyalty_cards": [ { "id": "slp8q", "name": "", "ref": "av-33489", "balance": 13.5 } ], "custom_fields": {}}

2.2. List Customers

Returns the customers of a customer list. Some filters can be passed.

Endpoint:
GET /customer_lists/:customer_list_id/customers
Access level:
location, account

Request parameters:

NameDescription
private_refReturns customers having this private_ref.
emailFilter customers by email. Wildcards (*) can be used.
phoneFilter customers by phone. Wildcards (*) can be used.

Example request:

GET /customer_lists/ag8u4/customers?phone=0123*

[ { "id": "asdf2", "first_name": "Charles", "last_name": "Moore", "phone": "0123456789" ... }]

2.3. Create Customer

Creates a new customer. The only mandatory fields are the first and last name.

Endpoint:
POST /customer_lists/:customer_list_id/customers
Access level:
location, account

Request parameters:

NameTypeDescription
private_ref optionalstringThe customer internal id, visible only to the client who set it. Used for customer lookup.
email optionalstringEmail
first_namestringFirst name
last_namestringLast name
gender optionalstringIf defined, must be either male or female
birth_date optionaldateBirth date (eg. 1999-01-01)
company_name optionalstringCompany name
phone optionalstringPhone number
address_1 optionalstring1st line of address
address_2 optionalstring2nd line of address
postal_code optionalstringPostal code
city optionalstringCity
state optionalstringState
country optionalstringCountry
latitude optionaldecimalLatitude
longitude optionaldecimalLongitude

Example request:

POST /customer_lists/ag8u4/customers

{ "first_name": "Charles", "last_name": "Moore", "email": "charles.moore@xxx.com", "private_ref": "charles.moore@xxx.com"}

2.4. Update Customer

Updates a customer.

Endpoint:
PUT /customer_lists/:customer_list_id/customers/:customer_id
Access level:
location, account

Example request:

PUT /customer_lists/ag8u4/customers/asdf2

{ "first_name": "Claude"}

3. Loyalty Cards

3.1. Retrieve Loyalty Card

Returns a loyalty card.

A customer can have zero, one or many loyalty cards.

name identifies the loyalty scheme or the name of a particular campaign. Each card must have a unique name for any given customer. An empty ("") name is acceptable and will generally be used for a location running a unique loyalty program.

The ref must be unique for a given customer list and a given name.

The balance is updated automatically by HubRise when a loyalty operation is created. This field cannot be changed through the API.

Endpoint:
GET /customer_lists/:customer_list_id/loyalty_cards/:loyalty_card_id
Access level:
location, account

Example request:

GET /customer_lists/smpre3/loyalty_cards/slp8q

{ "id": "slp8q", "customer_id": "ve343", "name": "", "ref": "av-33489", "balance": 13.5}

3.2. List Loyalty Cards

Returns the loyalty cards belonging to a customer list. Some filters can be passed.

Endpoint:
GET /customer_lists/:customer_list_id/loyalty_cards
Access level:
location, account

Request parameters:

NameDescription
nameFilters the loyalty cards by name.
refFilters by ref.
customer_idReturns the cards belonging to a particular customer.

Example request: retrieve by name and ref

GET /customer_lists/smpre3/loyalty_cards?name=&ref=av-33489

[ { "id": "slp8q", "customer_id": "ve343", "name": "", "ref": "av-33489", "balance": 13.5 }]

Example request: retrieve the loyalty cards belonging to a customer

GET /customer_lists/smpre3/loyalty_cards?customer_id=ve343

[ { "id": "slp8q", "customer_id": "ve343", "name": "", "ref": "av-33489", "balance": 13.5 }, { "id": "65rsp", "customer_id": "ve343", "name": "kiosk", "ref": "31", "balance": 1.5 }]

3.3. Create Loyalty Card

Creates a new loyalty card for a customer.

Endpoint:
POST /customer_lists/:customer_list_id/loyalty_cards
Access level:
location, account

Request parameters:

NameTypeDescription
customer_idstringThe customer's id. Must exist or the request will fail.
namestringThe loyalty card scheme name. Must be unique among the cards owned by the same customer. Mandatory parameter, but "" is an acceptable value.
ref optionalstringThe unique reference of the card. If defined, it must be unique among all the cards of the same customer list having the same name.

Example request:

POST /customer_lists/smpre3/loyalty_cards

{ "customer_id": "ve343", "name": "", "ref": "av-33489"}

If the request succeeds, the loyalty card is created with an initial balance set to 0.0

3.4. Update Loyalty Card

Update a loyalty card.

Endpoint:
PUT /customer_lists/:customer_list_id/loyalty_cards/:loyalty_card_id
Access level:
location, account

Request parameters:

NameTypeDescription
name optionalstringThe loyalty card scheme name.
ref optionalstringThe unique reference of the card.

Example request:

PUT /customer_lists/smpre3/loyalty_cards/slp8q

{ "ref": "av-20103"}

Note that only the name and the ref can be updated. It's not possible to change the customer_id.

balance cannot be changed directly as well. To update it, just create an operation.

4. Loyalty Operations

4.1. Retrieve Operation

Returns a loyalty card operation.

Endpoint:
GET /customer_lists/:customer_list_id/loyalty_cards/:loyalty_card_id/operations/:operation_id
Access level:
location, account

Example request:

GET /customer_lists/smpre3/loyalty_cards/slp8q/operations/22kmp

{ "id": "22kmp", "customer_id": "ve343", "created_at": "2017-01-18T12:37:21+01:00", "order_location_id": "psm98", "order_id": "mapcm", "reason": "Points earned", "delta": 4.2, "new_balance": 17.7}

4.2. List Operations

Returns the operations on a given loyalty card, sorted by descending chronological order.

Endpoint:
GET /customer_lists/:customer_list_id/loyalty_cards/:loyalty_card_id/operations
Access level:
location, account

Example request:

GET /customer_lists/smpre3/loyalty_cards/slp8q/operations

[ { "id": "22kmp", "customer_id": "ve343", "created_at": "2017-01-18T12:37:21+01:00" ... }, ...]

4.3. Create Operation

Create a loyalty card operation and updates the balance accordingly.

Endpoint:
POST /customer_lists/:customer_list_id/loyalty_cards/:loyalty_card_id/operations
Access level:
location, account

Request parameters:

NameTypeDescription
order_id optionalstringAttach this operation to a particular order. If defined, an order with this id must exist or the request will fail. An order can be attached to several operations.
reason optionalstringDescribes how the points were obtained/redeemed. The customer will typically see this field when he checks his loyalty account operations from a website.
deltadecimalThe number of points to add to the customer balance. Use a negative number to remove points.

Example request:

POST /customer_lists/smpre3/loyalty_cards/slp8q/operations

{ "order_id": "mapcm", "reason": "Points earned", "delta": 4.2}

If the request succeeds, the operation's new_balance is automatically calculated, as well as the customer's balance.

An operation CANNOT be deleted or updated. An operation is voided by creating an opposite operation.