Activities

You can use the activities API to view, track and update activities in LoyaltyLion. Activities are performed by customers and linked to rules in LoyaltyLion, e.g. “post a comment and earn 100 points”.

If you want to track or update orders (which can also be associated with rules), you should use the Orders API instead.

GET /v2/activities

Returns a pageable list of all activities.

Request

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

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

Response

This endpoint will return a list of activity resources.

FieldTypeDescription
idintegerUnique id of activity in LoyaltyLion
merchant_idstringIf this activity is linked to a resource in your store, this will the id of the resource
statestringThe state of this activity, one of pending , declined , approved or void
ruleobjectAn object containing the linked activity rule’s id and name (e.g. “$purchase”)
customerobjectAn object containing the linked customer’s id and other fields
created_atstringAn ISO8601 timestamp representing when this activity was completed in LoyaltyLion

Example

curl \
  --url 'https://api.loyaltylion.com/v2/activities?limit=50&page=2' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json'

POST /v2/activities

Use this endpoint to track an activity to LoyaltyLion. When tracking an activity, if an applicable rule exists it will be triggered (based on the name of the activity).

You should not use the this API to track and reward purchases. Instead you should use the Orders API which allows you to send important information specific to orders, such as the order total and payment status.

Request

You must provide a JSON payload with the following fields:

FieldTypeRequiredDescription
namestringyesA built-in or custom activity rule name. If you’re tracking a custom rule, this should be the rule identifier; if you’re tracking a built-in activity, the name must be prefixed with a $, e.g. $signup
customer_idstringyesA unique ID for the customer involved in the activity. This should be your internal ID for this customer
customer_emailstringyesThe email address for the customer
merchant_idstringnoA unique ID used to link this activity to an internal resource in your system. If provided, you will be able to update the state of this activity later using the activity update endpoint
statestringnoThe initial state of this activity. If provided will be used for any applicable rule processing. Must be one of: pending and approved
datestringnoThe date this activity occured, as an ISO8601 timestamp. Will default to now if not provided
ip_addressstringnoThe IP address of the customer involved in this activity. Used in combination with user_agent to track referrals
user_agentstringnoThe full user agent string of the customer involved in this activity. Used in combination with ip_address to track referrals
propertiesobjectnoA JSON object which will be stored along with this activity and used in rules or searching
referral_idstringnoA LoyaltyLion referral ID - more details
tracking_idstringnoA LoyaltyLion email tracking ID - more details
guestbooleannoA boolean value indicating if the customer is a guest. The default is false.

Response

Returns a 201 Created response if the activity was tracked successfully. If the activity was invalid, a 422 Unprocessable Entity response will be returned.

Example

curl -X POST \
  --url 'https://api.loyaltylion.com/v2/activities' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "posted_comment",
    "customer_id": "1001",
    "customer_email": "alice@example.com",
    "merchant_id": "355a9f04"
  }'

PUT /v2/activities/:name/:merchant_id

You can inform us about a change in an activity with this endpoint, which can be used to tell us when an activity is approved or declined.

For example, if you track a review which defaults to “pending”, and your moderator then approves the review, you can send LoyaltyLion an update informing us it has been approved.

To update an activity you’ll need the activity name (e.g. review) and the merchant_id you sent to LoyaltyLion when you first tracked the activity.

Request

You must provide a JSON payload with the following fields:

FieldTypeRequiredDescription
statestringyesThe new state of this activity. Must be one of: approved and declined
datestringnoThe date the change occured, as an ISO8601 timestamp. If not provided will default to now

Response

Returns a 204 No Content response if the update was applied. If the activity failed to update (e.g. the requested state change was invalid), a 422 Unprocessable Entity response will be returned.

Example

curl -X PUT \
  --url 'https://api.loyaltylion.com/v2/activities/posted_comment/355a9f04' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "state": "declined"
  }'