Record Activities on a Program Membership

Activities are events that change the points a specific user has in a program.

The POST /v2/program-memberships/:program_membership_id/activities endpoint lets you record activities, offering a seamless way to update the points that a user has and the activity that they took to earn those points.

How Activities Work in Hang

An activity in Hang represents an event that alters a user's point balance in a program. This can include actions like completing a challenge, making a purchase, or any other event you define that should affect a user's points. Hang's API lets you log these activities to ensure the points are updated and any necessary follow-up actions are triggered.

Registering New Activities

Creating a new activity is as straightforward as making a POST request to the /v2/program-memberships/:program_membership_id/activities endpoint.

Request Parameters

• idempotency_key (required): A unique key to prevent double processing.

• program_membership_id (required): The ID of the user's program membership.

• activity (required): An object representing the activity to record.

The activity object contains:

• activity_type_id (required): The type of activity.

• value (required): The value of the activity in points.

• transaction_timestamp (required): Unix timestamp of the activity.

• line_items (optional): Array of line items related to the activity. Line item IDs will correspond to any item related quests and bonuses. If any item ids in the array match a restricted to ID on a quest, this will qualify towards the quest requirement.

Each item in the line_items array contains:

• item_id: Identifier for the item.

• value: Value for the line item in points.

• group_id (optional): Group for the item.

Example Request

Here's an example of a valid POST request to the activity endpoint:

curl -X POST 'https://loyalty.hang.xyz/partner-api/v2/program-memberships/12345/activities' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "unique-key-101",
    "activity": {
      "activity_type_id": "activity_type_1",
      "value": "50",
      "transaction_timestamp": 1633887337,
      "line_items": [
        {
          "item_id": "item_1",
          "value": 30,
          "group_id": "group_1"
        }
      ]
    }
  }'

Response

If successful, the API will return a 200 OK status along with the idempotency key for confirmation.

Example Response

{
  "idempotency_key": "unique-key-101"
}

Implementing Activities in Your Backend

After making the API call, Hang will process the activity and update the user's points accordingly. Use the idempotency key in the response to confirm that the activity was processed successfully without duplication.

Error Handling

If the API encounters an error, a relevant error message will be returned to guide you through the troubleshooting process.