BETA: Please note that the current endpoints are considered beta. It is possible there may be changes before these endpoints are finalised.
Customers
Get a Customer
Get a customer
get /organizations/{organizationId}/customers/{customerId}
Parameters
Name | Type | In | Description |
---|---|---|---|
organizationId | string | path | Organization ID |
customerId | string | path | Customer ID |
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"
}
404: not_found: Not Found response.
List 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
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"
}
]
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 |
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 |
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 |