Customers

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

GET /v2/customers

Returns a pageable list of all customers. Responses will contain a prev and next cursor which can be used to fetch the next page of results, if any. See cursor pagination guidance

Request

You can pass the following optional query parameters with the request.

ParamDescription
emailReturn only customers whose email contains the specified string
since_idReturn only customers whose id is after the specified id
cursorA cursor to retrieve another page of results. Cursor pagination guidance
limitNumber of customers to return per request. Must be 1-500 (default: 100)
created_at_minReturn only customers created at or after this date (ISO 8601 format)
created_at_maxReturn only customers created at or before this date (ISO 8601 format)
updated_at_minReturn only customers last updated at or after this date (ISO 8601 format)
updated_at_maxReturn only customers last updated at or before this date (ISO 8601 format)

Response

This endpoint returns 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 (for example, name)
metadataobjectDepending on your platform, this may include platform specific metadata
birthdaystring or nullAn ISO 8601 date representing the customers birthday
blockedbooleanTrue if this customer has been blocked from the loyalty program
guestbooleanTrue if we’ve determined this customer isn’t fully registered with your store
enrolledbooleanTrue if this customer is member of the loyalty program
enrolled_atstring or nullIf enrolled, an ISO 8601 timestamp representing when they joined the program
referred_byobject or nullIf customer was referred, an object containing the id and merchant_id of the referring customer
loyalty_tier_membershipobject or nullIf Loyalty Tiers are enabled and the customer is enrolled, an object containing the customer’s current tier
insights_segmentstring or 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, for example, https://prz.io/KzByQ2Fa
created_atstringAn ISO 8601 timestamp representing when this customer was created in LoyaltyLion
updated_atstringAn ISO 8601 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 'Content-Type: application/json'

PATCH /v2/customers/:merchant_id

Updates selected properties on a customer.

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

Request

Only the properties below can be updated via this endpoint. None of the properties are required, but you must provide a JSON payload with at least one to update the customer:

FieldTypeDescription
birthdaystringA customer’s birthday in YYYY-MM-DD format
blockedbooleantrue if the customer should be blocked from the loyalty program, false if they should not

Response

  • Returns a 200 response with the updated body of the customer if the update was successful.
  • If no customer matching the :merchant_id can be found, then a 404 Not Found response is returned.
  • If the value for a property is sent in the wrong format, a 422 Unprocessable Entity response is returned.

Example

curl -X PATCH \
  --url 'https://api.loyaltylion.com/v2/customers/1001' \
  --header 'Content-Type: application/json' \
  --data '{
      "customer": {
        "birthday": "1990-05-10"
      }
  }'

POST /v2/customers/:merchant_id/points

Award a number of points to a customer. These points are 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’s 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 no customer matching the :merchant_id can be found, then a 404 Not Found response is returned.
  • If the points field is missing or invalid, a 422 Unprocessable Entity response is returned.

Example

curl -X POST \
  --url 'https://api.loyaltylion.com/v2/customers/1001/points' \
  --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’s 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 no customer matching the :merchant_id can be found, then a 404 Not Found response is returned.
  • If the points field is missing or invalid, a 422 Unprocessable Entity response is returned.

Example

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