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.

Param	Description
`since_id`	Return only activities whose `id` is after the specified id
`limit`	Number of activities to return per request. Must be between 1-500 (default: 100)
`page`	Page to show (default: 1)
`created_at_min`	Return only activities created after this date (ISO8601 format)
`created_at_max`	Return only activities created before this date (ISO8601 format)
`updated_at_min`	Return only activities last updated after this date (ISO8601 format)
`updated_at_max`	Return only activities last updated before this date (ISO8601 format)

Response

This endpoint will return a list of activity resources.

Field	Type	Description
`id`	`integer`	Unique id of activity in LoyaltyLion
`merchant_id`	`string`	If this activity is linked to a resource in your store, this will the id of the resource
`state`	`string`	The state of this activity, one of `pending` , `declined` , `approved` or `void`
`rule`	`object`	An object containing the linked activity rule’s id and name (e.g. “$purchase”)
`customer`	`object`	An object containing the linked customer’s id and other fields
`created_at`	`string`	An 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:

Field	Type	Required	Description
`name`	`string`	yes	A 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_id`	`string`	yes	A unique ID for the customer involved in the activity. This should be your internal ID for this customer
`customer_email`	`string`	yes	The email address for the customer
`merchant_id`	`string`	no	A 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
`state`	`string`	no	The initial state of this activity. If provided will be used for any applicable rule processing. Must be one of: `pending` and `approved`
`date`	`string`	no	The date this activity occured, as an ISO8601 timestamp. Will default to now if not provided
`ip_address`	`string`	no	The IP address of the customer involved in this activity. Used in combination with `user_agent` to track referrals
`user_agent`	`string`	no	The full user agent string of the customer involved in this activity. Used in combination with `ip_address` to track referrals
`properties`	`object`	no	A JSON object which will be stored along with this activity and used in rules or searching
`referral_id`	`string`	no	A LoyaltyLion referral ID - more details
`tracking_id`	`string`	no	A LoyaltyLion email tracking ID - more details
`guest`	`boolean`	no	A 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:

Field	Type	Required	Description
`state`	`string`	yes	The new state of this activity. Must be one of: approved and declined
`date`	`string`	no	The 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"
  }'