BETA: Please note that the current endpoints are considered beta. It is possible there may be changes before these endpoints are finalised.

Customers

List all customers for an organization. The result list is paged by 1000 results. Use X-Next-Page to retrieve the next page of results. Tip: Make sure you URI encode your parameter values, for example the + in the phone number should be encoded to %2B.

get /organizations/{organizationId}/customers

Parameters

Name	Type	In	Description
`organizationId`	string	path	Organization ID
`after`	string	query	The cursor to use for pagination. Do not use this field manually it will be automatically provided in the response headers (see Paging guide).
`sort`	string	query	How to sort the returned customer list. "created", "updated"
`email`	string	query	Give a valid email address to search all customers - this will find and return a list of customers with the exact email address given.
`phoneNumber`	string	query	Give a valid phone number to search all customers. Note that we cannot guarantee unique key on phone numbers.

Responses

200: OK response.Customer[]

[
  {
    "createdAt": "2021-10-20T14:51:16Z",
    "dob": "2021-10-20",
    "email": "john@example.com",
    "firstName": "John",
    "gender": "MALE",
    "hasAgreedToMarketing": true,
    "id": "01FCCGYZA9JPQ97HBSTKW0KT7P",
    "lastName": "Smith",
    "phoneNumber": "+61411222333",
    "statistics": {
      "lastPointsEarnedAt": "2021-08-23T02:06:24.000Z",
      "lastPointsRedeemedAt": "2021-03-17T04:27:06.000Z",
      "lastSpentAt": "2021-08-23T02:06:23.000Z",
      "pointsBalance": 3125,
      "totalPointsEarned": 4523,
      "totalPointsRedeemed": 1398,
      "totalSpend": 3687
    },
    "updatedAt": "2021-10-21T18:34:45Z"
  },
  {
    "createdAt": "2021-10-20T14:51:16Z",
    "dob": "2021-10-20",
    "email": "john@example.com",
    "firstName": "John",
    "gender": "MALE",
    "hasAgreedToMarketing": true,
    "id": "01FCCGYZA9JPQ97HBSTKW0KT7P",
    "lastName": "Smith",
    "phoneNumber": "+61411222333",
    "statistics": {
      "lastPointsEarnedAt": "2021-08-23T02:06:24.000Z",
      "lastPointsRedeemedAt": "2021-03-17T04:27:06.000Z",
      "lastSpentAt": "2021-08-23T02:06:23.000Z",
      "pointsBalance": 3125,
      "totalPointsEarned": 4523,
      "totalPointsRedeemed": 1398,
      "totalSpend": 3687
    },
    "updatedAt": "2021-10-21T18:34:45Z"
  },
  {
    "createdAt": "2021-10-20T14:51:16Z",
    "dob": "2021-10-20",
    "email": "john@example.com",
    "firstName": "John",
    "gender": "MALE",
    "hasAgreedToMarketing": true,
    "id": "01FCCGYZA9JPQ97HBSTKW0KT7P",
    "lastName": "Smith",
    "phoneNumber": "+61411222333",
    "statistics": {
      "lastPointsEarnedAt": "2021-08-23T02:06:24.000Z",
      "lastPointsRedeemedAt": "2021-03-17T04:27:06.000Z",
      "lastSpentAt": "2021-08-23T02:06:23.000Z",
      "pointsBalance": 3125,
      "totalPointsEarned": 4523,
      "totalPointsRedeemed": 1398,
      "totalSpend": 3687
    },
    "updatedAt": "2021-10-21T18:34:45Z"
  }
]

Examples

Syncing customers on a schedule

To sync the full database on a schedule (rather than using webhook events) without needing to refetch all customers can use the sort=updated query parameter. This will fetch customers starting with those updated most recently. Continue to fetch next pages until you pass the updated timestamp from the last scheduled run.

The following example demonstrates the approach using fetch in Typescript (note: limited error handling for brevity).

async function getUpdatedCustomers(organizationId: string, updatedAt: Date | null) {
  let customers = [];
  let path: string | null = `/organizations/${organizationId}/customers?sort=updated`;

  do {
    const url = new URL(path, "https://api.loke.global");
    const response = await fetch(url, {
      headers: { Authorization: "Bearer my_access_token" },
    });
    if (!response.ok) throw new Error("Network response was not OK");
    path = response.headers.get("X-Next-Page");

    customers.push(await response.json());

    const lastCustomer =  customers[customers.length - 1];
    if (!lastCustomer || (updatedAt && new Date(lastCustomer.updatedAt) < updatedAt)) {
      // don't continue, even if more pages
      path = null;
    }
  } while (path);

  return { customers, updatedAt: customers[0]?.updatedAt ?? updatedAt };
}

async function doScheduledJob() {
  // load the job params, in particular last known updatedAt
  const job = await getMyJob();

  const {customers, updatedAt} = await getUpdatedCustomers(
    job.organizationId,
    job.updatedAt // will be null on first run
  );

  // do something with customers
  await updateCustomersInMySystem(customers);

  // remember the new updatedAt value for next run
  await updateMyJob(job.id, { updatedAt });
}

List memberships

List all customer-lists that a customer is a member of. The result list is paged by 10 results. Use X-Next-Page to retrieve the next page of results

get /organizations/{organizationId}/customers/{customerId}/memberships

Parameters

Name	Type	In	Description
`organizationId`	string	path	Organization ID
`after`	string	query	The cursor to use for pagination. Do not use this field manually it will be automatically provided in the response headers (see Paging guide).
`customerId`	string	path	Customer ID

Responses

200: OK response.CustomerListTiny[]

[
  {
    "id": "01FCCGYZA9JPQ97HBSTKW0KT7P",
    "name": "Loyal Customers"
  },
  {
    "id": "01FCCGYZA9JPQ97HBSTKW0KT7P",
    "name": "Loyal Customers"
  }
]

Models

Customer

Name	Type	Description
id	string	Unique ID of the Customer
createdAt	string	(optional) The date and time that the Customer was created
updatedAt	string	(optional) The date and time that the Customer was last updated
dob	string	(optional) The Customers date of birth in YYYY-MM-DD format
email	string	(optional) The Customers email address
firstName	string	Customer first name or given name
gender	string	(optional) The Customers gender
hasAgreedToMarketing	boolean	(optional) If the Customer has agreed to marketing
lastName	string	Customer last name or surname
phoneNumber	string	(optional) The Customers mobile phone number
statistics	CustomerStatistics	(optional)

CustomerStatistics

Name	Type	Description
lastPointsEarnedAt	string	(optional) Date and time of last points earned by the Customer
lastPointsRedeemedAt	string	(optional) Date and time of last redeemed points by the Customer
lastSpentAt	string	(optional) The date of the Customers last spend
pointsBalance	integer	(optional) The Customers current points balance
totalPointsEarned	integer	(optional) The total points earned over the Customers lifetime
totalPointsRedeemed	integer	(optional) Total points earned over lifetime of the Customer
totalSpend	integer	(optional) The total spend amount of the Customer, in the lowest common denominator e.g. cents

CustomerTiny

Name	Type	Description
id	string	Unique ID of the Customer
email	string	(optional) The Customers email address
firstName	string	Customer first name or given name
lastName	string	Customer last name or surname
phoneNumber	string	(optional) The Customers mobile phone number

CustomerListTiny

A customer list

Name	Type	Description
id	string	(optional) Unique ID of the customer list
name	string	(optional) The name of the customer list

Customers

Get a Customer

Parameters

Responses

List Customers

Parameters

Responses

Examples

Syncing customers on a schedule

List memberships

Parameters

Responses

Models

Customer

CustomerStatistics

CustomerTiny

CustomerListTiny

In this article