mParticle Event - Guest
This includes users creating/updating events triggered as they happen in the Punchh system.
In a user update event, the previous_changes attribute (array) contains updated user attributes tracked as database field changes. Certain attributes are always included in payload even though they are not present in previous_changes, such as apple_loyalty_pass_url, android_loyalty_pass_url and account balance information.
When Disable sending default user attributes to mParticle is set to No, all supported user attributes are included in the event payload along with the updated user attributes in previous_changes.
When the setting is set to Yes, only attributes present in previous_changes are generally included, along with certain attributes mentioned above are always included.
Note: Punchh sends guest events for users with the following statuses: active, banned, or deactivated. Guest events are not sent for deleted, anonymized, or archived users, as personally identifiable information (PII) is not stored once a guest is moved into these statuses. However, if the option to generate events for deleted guests is enabled for the business in the Punchh platform, events will be sent for deleted users.
{
"errors": null,
"raw_response": null,
"status": "success",
"status_code": 202,
"transaction_id": "",
"vendor_request": {
"environment": "production",
"events": [
{
"data": {
"custom_attributes": {
"event_action": "update",
"event_name": "users",
"event_type": "",
"previous_changes": "current_sign_in_at,current_sign_in_ip,last_sign_in_at,last_sign_in_ip,updated_at"
},
"custom_event_type": "other",
"event_name": "users"
},
"event_type": "custom_event"
}
],
"partner_identities": {
"punchh_user_id": "652191870"
},
"user_attributes": {
"Punchh_account_balance_net_balance": 0,
"Punchh_account_balance_net_debits": 0,
"Punchh_account_balance_total_lifetime_points": 0,
"Punchh_account_balance_total_point_credits": 0,
"Punchh_birthday": "1904-05-10",
"Punchh_business_id": 844,
"Punchh_created_at": "2022-03-31T00:43:28Z",
"Punchh_current_sign_in_at": "2022-03-31T11:45:48Z",
"Punchh_current_sign_in_ip": "172.17.0.5",
"Punchh_email": "test@example.com",
"Punchh_first_name": "FIRST_NAME_GOES_HERE",
"Punchh_guest_type": "Loyalty",
"Punchh_joined_at": "2022-03-31T00:43:28Z",
"Punchh_last_activity_at": "2022-03-31T00:43:28Z",
"Punchh_last_name": "LAST_NAME_GOES_HERE",
"Punchh_last_sign_in_at": "2022-03-31T11:45:46Z",
"Punchh_last_sign_in_ip": "172.17.0.6",
"Punchh_last_user_agent": "SampleAPI/3.0 test",
"Punchh_marketing_email_opt_in": true,
"Punchh_marketing_email_subscription": true,
"Punchh_marketing_pn_opt_in": true,
"Punchh_marketing_pn_subscription": true,
"Punchh_referral_code": "REFERRAL_CODE_GOES_HERE",
"Punchh_signup_channel": "MobileEmail",
"Punchh_sms_subscription": false,
"Punchh_terms_and_conditions_opt_in": false,
"Punchh_unsubscribed": false,
"Punchh_updated_at": "2022-03-31T11:45:48Z",
"Punchh_user_id": 652191870,
"Punchh_user_status": "active",
"Punchh_zip_code": "94087",
"apple_loyalty_pass_url": "APPLE_LOYALTY_PASS_URL_GOES_HERE",
"android_loyalty_pass_url": "ANDROID_LOYALTY_PASS_URL_GOES_HERE"
},
"user_identities": {
"email": "testuser@gmail.com"
}
},
"vendor_response": null
}
Response Parameters
| Event Name | Type | Description |
|---|---|---|
| data.custom_attributes.event_action | String | Operation associated with the event (e.g., create/update/delete for user, POS/console/online for check-ins, etc.) |
| data.custom_attributes.event_name | String | Name of the event, such as user, check-ins, redemption, etc. |
| data.custom_attributes.event_type | String | Type of the event (e.g., gift or loyalty for check-ins, etc.) |
| data.custom_attributes.previous_changes | Array | Lists the specific user attributes that have been updated in a particular event within the Punchh system. For example, if the phone number and address are updated in the guest profile, previous_changes will only include the keys for the attributes that were updated - in this case, "phone" and "address". |
| user_attributes.Punchh_account_balance_net_balance | Float | Net available balance of the current account. This value always shows the available balance of the user, whether visits, banked rewards, or points. |
| user_attributes.Punchh_account_balance_net_debits | Float | Total points redeemed/donated/transferred by the user |
| user_attributes.Punchh_account_balance_total_lifetime_points | Float | Sum of all the loyalty points earned by a user from the time the user signed up (excluding expired points) |
| user_attributes.Punchh_account_balance_total_point_credits | Float | Total points credits of the user, including initial points (e.g., membership level bump) |
| user_attributes.Punchh_birthday | Date | Birthday of the user in YYYY-MM-DD format |
| user_attributes.Punchh_business_id | Integer | Business ID in Punchh |
| user_attributes.Punchh_created_at | Date_time | Date/time when the user was created in the system in ISO 8601 format |
| user_attributes.Punchh_current_sign_in_at | Date_time | Date and time when a user most recently logged into the system |
| user_attributes.Punchh_current_sign_in_ip | String | IP address of the device from which the user has most recently logged in |
| user_attributes.Punchh_email | String | Email address of the user |
| user_attributes.Punchh_first_name | String | First name of the user |
| user_attributes.Punchh_guest_type | String | Type of user (i.e., eClub or loyalty) |
| user_attributes.Punchh_joined_at | Date_time | Timestamp when the loyalty user signed up |
| user_attributes.Punchh_last_activity_at | Date_time | User’s last activity timestamp |
| user_attributes.Punchh_last_name | String | Last name of the user |
| user_attributes.Punchh_last_sign_in_at | Date_time | Timestamp of the last user sign-in |
| user_attributes.Punchh_last_sign_in_ip | String | IP address of the system from which the user last signed in |
| user_attributes.Punchh_last_user_agent | String | The device agent used by the user during the last login |
| user_attributes.Punchh_marketing_email_opt_in | Boolean | Whether the user has subscribed to marketing emails or not |
| user_attributes.Punchh_marketing_email_subscription | Boolean | Whether the user has subscribed to marketing emails or not |
| user_attributes.Punchh_marketing_pn_opt_in | Boolean | Whether the end-user has subscribed to marketing push notifications or not |
| user_attributes.Punchh_marketing_pn_subscription | Boolean | Whether the end-user has subscribed to marketing push notifications or not |
| user_attributes.Punchh_referral_code | String | Referral code of the user to refer other users |
| user_attributes.Punchh_signup_channel | String | Sign-up channel of the user |
| user_attributes.Punchh_sms_subscription | Boolean | Whether the user has subscribed to SMS services or not |
| user_attributes.Punchh_terms_and_conditions_opt_in | Boolean | Whether a user has accepted the terms and conditions of a business or not |
| user_attributes.Punchh_unsubscribed | Boolean | Whether the user has unsubscribed from marketing email notifications |
| user_attributes.Punchh_updated_at | Date_time | Date/time when the user was updated in the system in ISO 8601 format |
| user_attributes.Punchh_user_id | Integer | ID of the user in the Punchh system |
| user_attributes.Punchh_user_status | String | Status of the user (i.e., active, banned, or deactivated) Note: Punchh does not send guest events for users with deleted, anonymized, or archived status, as personally identifiable information (PII) is not stored once a guest is moved into these statuses.However, if the option to generate events for deleted guests is enabled for the business in the Punchh platform, events will be sent for deleted users. |
| user_attributes.Punchh_zip_code | String | Zip code where the user lives |
| user_attributes.Punchh_email_confirmation_url | String | URL that is sent to a user as part of an email verification process. This URL is designed to confirm the user's email address, ensuring it is valid and belongs to the user. |
| user_attributes.apple_loyalty_pass_url | String | URL for the guest to save their Apple Wallet loyalty pass. Included when passes are enabled for the business. Contact your Punchh representative to update this Punchh platform configuration. Note: apple_loyalty_pass_url and android_loyalty_pass_url are always included in "guest_create" and "guest_update", regardless of the Disable sending default user attributes to mParticle setting. These attributes do not appear in the previous_changes array because their values are computed dynamically and are not tracked as database field updates. For other events (for example, Loyalty Check-in), these attributes are included or excluded from the guest data based on the value of the Disable sending default user attributes to mParticle setting. See Exclude User Profile Data from Custom Events |
| user_attributes.android_loyalty_pass_url | String | URL for the guest to save their Google Wallet loyalty pass. Included when passes are enabled for the business. Contact your Punchh representative to update this Punchh platform configuration. See the note in user_attributes.apple_loyalty_pass_url above for inclusion behavior details. |
| user_attributes.Punchh_terms_and_conditions_opt_in | Boolean | Whether the terms and conditions of a business have been accepted by an end-user or not |
| user_attributes.Punchh_unsubscribe_reason | String | Reason for unsubscribing marketing email notifications |
| user_identities.email | String | Email address in Punchh used as the user's identity |
See the table in the Response Parameters section of Event - Guest for descriptions of additional parameters, if any, in the custom_attributes object. Remove the prefix "Punchh" from the parameter name when searching the description of a parameter.