Customers

This section of the documentation goes through the core Customers endpoint. This endpoint allows you to handle customer authentication as well as manage and update customers' information such as contact name, email address and metadata.

A customer in Chec is anyone who makes a purchase and has the ability to create an account. Requests to the customers endpoint will return the full customers object with data to create a customer's authorized view containing information such as their contact name and list of orders.

Send login token

This endpoint helps to authenticate and resolve a customer in the merchant account by accepting an email address as an argument and sending a one-click login email. The email contains a short-lived magic link for the user to access a protected route only permitted with the token. The login() method uses POST v1/customers/email-token to log a customer in to an authorized route to access the customers resource. The method below will exchange the token for a JSON web token (JWT) which is scoped to that particular customer granting access to that customer's orders, addresses, etc.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.customer.login('[email protected]', 'https://yourwebsite.com/login/callback').then((token) => console.log(token));

Example request using cURL:

curl -X POST \
    "https://api.chec.io/v1/customers/email-token" \
    -H "Content-Type: application/json" \
    -d '{"email":"[email protected]","base_url":"https://yourwebsite.com/login/callback"}'

When this endpoint is called in a login flow, the subsequent method below to call would exchange the token for a JSON web token to log the customer in to a protected route.

Get access token

Once a customer has entered their email address in the previous step and clicked on the one-time login link they received in their email, the link will send them back to your server (see https://yourwebsite.com/login/callback in the example above). In that callback handler, you can use the "get access token" method to exchange the token in the URL for a JSON web token.

The getToken() method uses POST /v1/customers/exchange-token to obtain a JSON web token scoped to the customer the provided token (returned from the login() method) belongs to. The returned JWT will be valid for 24 hours, and may be used to authorize API calls to the Customers API endpoints, such as get orders, etc.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.customer.getToken('1ae420a5-2f43-426f-8a61-516eabb56d33').then((jwt) => console.log(jwt));

Example request using cURL:

curl -X POST \
    "https://api.chec.io/v1/customers/exchange-token" \
    -H "X-Authorization: {token}" \
    -H "Content-Type: application/json" \
    -d '{"token":"1ae420a5-2f43-426f-8a61-516eabb56d33"}'

Update customer

The update() method uses PUT /v1/customers/{customer_id} to update an existing customer. All customer's data in this method are optional. Email addresses must be unique for your merchant's list of customers.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.customer.update({
  email: '[email protected]',
  firstname: 'Leslie',
  lastname: 'Lawless',
  external_id: 'MY_CRM_USER_123',
}, 'cstmr_K1YDR2qy29Qem6')
  .then((customer) => console.log(customer));

Example request using cURL:

curl -X PUT \
    "https://api.chec.io/v1/customers/cstmr_K1YDR2qy29Qem6" \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -d '{"email":"[email protected]","firstname":"Leslie","lastname":"Lawless","external_id":"MY_CRM_USER_123"}'

List orders for a customer

The getOrders() method uses GET /v1/customers/{customer_id}/orders to return a list of orders that belong to the provided customer ID. The response from this API is the same as List orders.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.customer.getOrders('cstmr_K1YDR2qy29Qem6').then((orders) => console.log(orders));

Example request using cURL:

curl -X GET \
    -G "https://api.chec.io/v1/customers/cstmr_f89398fs489g/orders" \
    -H "Authorization: Bearer {token}"

Get order for customer

The getOrder() method uses GET /v1/customers/{customer_id}/orders/{order_id} and returns a single order by its ID which belongs to the customer ID provided. The response from this API is the same as Retrieve order.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.customer.getOrder('ord_Kvg9l6zvnl1bB7').then((order) => console.log(order));

Example request using cURL:

curl -X GET \
    -G "https://api.chec.io/v1/customers/cstmr_f89398fs489g/orders/ord_Kvg9l6zvnl1bB7" \
    -H "Authorization: Bearer {token}"

Get customer

The about() method uses GET /v1/customers/{customer_id} to return information about the currently authorized customer by its ID.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.customer.about().then((customer) => console.log(customer));

Example request using cURL:

curl -X GET \
    -G "https://api.chec.io/v1/customers/cstmr_K1YDR2qy29Qem6" \
    -H "Authorization: Bearer {token}"

Get customer ID

The id() method returns the customer ID used during a successful login from local storage.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

console.log(commerce.customer.id());

Get customer token

The token() method returns the customer's JSON web token from local storage, if logged in.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

console.log(commerce.customer.token());

Check if customer is logged in

The isLoggedIn() method checks if a customer is logged in the current session and returns either true or false.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

console.log(commerce.customer.isLoggedIn());

Logout customer

The logout() method logs the customer out by clearing the customer state from the current session.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.customer.logout();