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, for example, “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 optional query parameters with the request.

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

Response

This endpoint returns a list of activity resources.

FieldTypeDescription
idintegerUnique id of activity in LoyaltyLion
merchant_idstring or nullIf this activity is linked to a resource in your store, merchant_id is the id of the resource
statestringThe state of this activity, one of pending, declined, approved or void
ruleobjectAn object containing the linked rule’s id and name (for example, ”$purchase”). When an activity is not linked to a rule, id and name will be null.
flowobjectAn object containing the linked flow id and other fields. Not provided if the activity is not linked to a flow.
customerobjectAn object containing the linked customer’s id and other fields
created_atstringAn ISO 8601 timestamp representing when this activity was completed in LoyaltyLion

Flows object

FieldTypeDescription
idintegerUnique id of flow
journey_idintegerUnique id of this customer’s journey through this flow. If a customer triggers a flow multiple times over their lifetime, they will receive a unique journey id each time.
namestringName of the flow
block_idstringId of the step in the flow that provided points. Note this id will change when a new version of a flow is published.

Example

curl \
  --url 'https://api.loyaltylion.com/v2/activities?limit=50' \
  --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’s triggered (based on the name of the activity).

You shouldn’t use the 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 $, for example, ”$signup
customer_idstringyesA unique ID for the customer involved in the activity. This should be your internal ID (from your ecommerce platform) 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 can update the state of this activity later using the activity update endpoint
statestringnoThe initial state of this activity. If provided, is used for any applicable rule processing. Must be one of: pending and approved
datestringnoThe date this activity occurred, as an ISO 8601 timestamp. Defaults 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 is 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 true.

Response

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

Example

curl -X POST \
  --url 'https://api.loyaltylion.com/v2/activities' \
  --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 (for example, 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

Response

Returns a 204 No Content response if the update is applied. If the activity fails to update (for example, the requested state change is invalid), a 422 Unprocessable Entity response is returned.

Example

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