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.

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

Response

This endpoint returns a list of activity resources.

Field	Type	Description
`id`	`integer`	Unique id of activity in LoyaltyLion
`merchant_id`	`string \| null`	If this activity is linked to a resource in your store, `merchant_id` is 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 rule’s `id` and `name` (for example, ”`$purchase`”). When an activity is not linked to a rule, `id` and `name` will be `null`.
`flow`	`object`	An object containing the linked flow id and other fields. Not provided if the activity is not linked to a flow.
`customer`	`object`	An object containing the linked customer’s id and other fields
`created_at`	`string`	An ISO 8601 timestamp representing when this activity was completed in LoyaltyLion

Flows object

Field	Type	Description
`id`	`integer`	Unique id of flow
`journey_id`	`integer`	Unique 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.
`name`	`string`	Name of the flow
`block_id`	`string`	Id 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:

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 $, for example, ”`$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 can update the state of this activity later using the activity update endpoint
`state`	`string`	no	The initial state of this activity. If provided, is used for any applicable rule processing. Must be one of: `pending` and `approved`
`date`	`string`	no	The date this activity occurred, as an ISO 8601 timestamp. Defaults 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 is 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 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:

Field	Type	Required	Description
`state`	`string`	yes	The 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"
  }'