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.

Param	Description
`email`	Return only customers whose `email` contains the specified string
`since_id`	Return only customers whose `id` is after the specified id
`cursor`	A cursor to retrieve another page of results. Cursor pagination guidance
`limit`	Number of customers to return per request. Must be 1-500 (default: 100)
`created_at_min`	Return only customers created at or after this date (ISO 8601 format)
`created_at_max`	Return only customers created at or before this date (ISO 8601 format)
`updated_at_min`	Return only customers last updated at or after this date (ISO 8601 format)
`updated_at_max`	Return only customers last updated at or before this date (ISO 8601 format)

Response

This endpoint returns a list of customer resources.

Field	Type	Description
`id`	`integer`	Unique id of customer in LoyaltyLion
`merchant_id`	`string`	Unique id of customer in your store
`email`	`string`	Email address of customer
`points_approved`	`integer`	Number of approved points
`points_pending`	`integer`	Number of pending points
`points_spent`	`integer`	Number of spent points
`rewards_claimed`	`integer`	Number of rewards the customer has claimed
`properties`	`object`	Any customer properties provided by your store (for example, name)
`metadata`	`object`	Depending on your platform, this may include platform specific metadata
`birthday`	`string \| null`	An ISO 8601 date representing the customers birthday
`blocked`	`boolean`	True if this customer has been blocked from the loyalty program
`guest`	`boolean`	True if we’ve determined this customer isn’t fully registered with your store
`enrolled`	`boolean`	True if this customer is member of the loyalty program
`enrolled_at`	`string \| null`	If enrolled, an ISO 8601 timestamp representing when they joined the program
`referred_by`	`object \| null`	If customer was referred, an object containing the id and merchant_id of the referring customer
`loyalty_tier_membership`	`object \| null`	If Loyalty Tiers are enabled and the customer is enrolled, an object containing the customer’s current tier
`insights_segment`	`string \| null`	If Insights are enabled, a string containing the customer’s current segment. One of `At Risk`, `Win Back`, `Loyal`
`referral_url`	`string`	This customer’s unique referral link, for example, https://prz.io/KzByQ2Fa
`created_at`	`string`	An ISO 8601 timestamp representing when this customer was created in LoyaltyLion
`updated_at`	`string`	An 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:

Field	Type	Description
`birthday`	`string`	A customer’s birthday in `YYYY-MM-DD` format
`blocked`	`boolean`	`true` 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:

Field	Type	Required	Description
`points`	`integer`	yes	The number of points to award. Must be greater than 0 and less than or equal to 1,000,000
`reason`	`string`	no	A 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:

Field	Type	Required	Description
`points`	`integer`	yes	The number of points to remove. Must be greater than 0
`reason`	`string`	no	A 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"
  }'