Customers

You can use the customers API to view and modify customers in LoyaltyLion.

GET /v2/customers

Returns a pageable list of all customers.

Request

You can pass the following query parameters with the request, all of which are optional.

ParamDescription
emailReturn only customers whose email contains the specified string
since_idReturn only customers whose id is after the specified id
limitNumber of customers to return per request. Must be between 1-500 (default: 100)
pagePage to show (default: 1)
created_at_minReturn only customers created after this date (ISO8601 format)
created_at_maxReturn only customers created before this date (ISO8601 format)
updated_at_minReturn only customers last updated after this date (ISO8601 format)
updated_at_maxReturn only customers last updated before this date (ISO8601 format)

Response

This endpoint will return a list of customer resources.

FieldTypeDescription
idintegerUnique id of customer in LoyaltyLion
merchant_idstringUnique id of customer in your store
emailstringEmail address of customer
points_approvedintegerNumber of approved points
points_pendingintegerNumber of pending points
points_spentintegerNumber of spent points
rewards_claimedintegerNumber of rewards the customer has claimed
propertiesobjectAny customer properties provided by your store (e.g. name)
metadataobjectDepending on your platform, this may include platform specific metadata
birthdaystring | nullAn ISO8601 date representing the customers birthday
blockedbooleanTrue if this customer has been blocked from the loyalty program
guestbooleanTrue if we have determined this customer is not fully registered with your store
enrolledbooleanTrue if this customer is member of the loyalty program
enrolled_atstring | nullIf enrolled, an ISO8601 timestamp representing when they joined the program
referred_byobject | nullIf customer was referred, an object containing the id and merchant_id of the referring customer
loyalty_tier_membershipobject | nullIf Loyalty Tiers are enabled and the customer is enrolled, an object containing the customer’s current tier
insights_segmentstring | nullIf Insights are enabled, a string containing the customer’s current segment. One of At Risk , Win Back , Loyal
referral_urlstringThis customer’s unique referral link, e.g. https://prz.io/KzByQ2Fa
created_atstringAn ISO8601 timestamp representing when this customer was created in LoyaltyLion
updated_atstringAn ISO8601 timestamp representing when this customer was last updated in LoyaltyLion

Example

curl \
  --url 'https://api.loyaltylion.com/v2/customers?created_at_min=2018-01-01' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json'

POST /v2/customers/:merchant_id/points

Award a number of points to a customer. These points will be approved and can be used immediately to redeem a reward.

The :merchant_id provided should match your own internal ID for this customer in your database.

Request

You must provide a JSON payload with the following fields:

FieldTypeRequiredDescription
pointsintegeryesThe number of points to award. Must be greater than 0 and less than or equal to 1,000,000
reasonstringnoA message that will be visible to customers in the Loyalty Panel and on the customer’s page in your LoyaltyLion merchant account

Response

Returns a 201 Created response if adding points was successful. If the points field is missing or invalid, a 422 Unprocessable Entity response will be returned.

Example

curl -X POST \
  --url 'https://api.loyaltylion.com/v2/customers/1001/points' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "points": 100,
    "reason": "Bonus for being an awesome customer"
  }'

POST /v2/customers/:merchant_id/remove_points

Immediately remove points from a customer’s approved points balance.

The :merchant_id provided should match your own internal ID for this customer in your database.

Request

You must provide a JSON payload with the following fields:

FieldTypeRequiredDescription
pointsintegeryesThe number of points to remove. Must be greater than 0
reasonstringnoA message that will be visible to customers in the Loyalty Panel and on the customer’s page in your LoyaltyLion merchant account

Response

Returns a 204 No Content response if adding points was successful. If the points field is missing or invalid, a 422 Unprocessable Entity response will be returned.

Example

curl -X POST \
  --url 'https://api.loyaltylion.com/v2/customers/1001/remove_points' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "points": 100,
    "reason": "Removing points awarded by mistake"
  }'