Pending Metrics Setup Guide
Overview
In Loyalty, metrics such as points act as a program currency that members earn based on their purchases or interactions which they can then redeem for rewards like discounts, free products, exclusive experiences, or other incentives. Earned metrics and the program benefits they unlock encourage repeat business and strengthen brand loyalty.
Some programs prefer to allow members to earn metrics and be able to use the value immediately for available rewards. However, other programs may prefer to delay the ability for metrics to be redeemed for rewards immediately. For this second type of program, Marigold has introduced the Pending Metric capability.
Configuring the system to initialize metrics in a pending status, instead of immediately activating the metrics, delays the ability to redeem the metrics. For brands whose customers may return purchased items, it reduces the risk of return fraud and complications that arise from redeeming value from returned items after the metrics were already used to redeem rewards.
This setup guide will explain how to configure the pending metrics feature, how to update/edit the configuration as needed, and how pending metrics are activated by the system.
Enabling pending metrics
Navigate to Program > Settings > Program Settings, then search for Pending Metric Handling program setting collection.
Program metric handling settings
Enabled: When turned ON, the system will accrue pending metric credit for purchases and potentially other member activity types, versus immediately activating and making the metric value available to members to redeem. When the toggle is OFF (the default setting), the system will immediately activate metric value for purchases and other member activity types, making it available for redemption right away.
Effectivity: The Effectivity setting allows programs to enable the Pending Metric behavior immediately, or to schedule it for a date/time to begin in the future. Note that Policy Start date/time and Timezone fields are displayed once Scheduled is selected.
Policy Start: This is the date and time that you can set the system to begin processing pending metric accruals.
Timezone: This is the timezone that you can set to have the system begin running the pending metric. Note that this is related to the policy start date/time.
Days Pending: This is the duration of time the pending metric value stays in a pending status before it is activated. This duration may be from 1 - 30 days.
Included Activity Types: The activity types that the system will evaluate when awarding pending metrics.
Important: By default, the Purchase activity type is included and expected to be processed in pending status. Other activity types can be added but that is an optional configuration.
By default, all metrics will be processed in pending status for any of the activity types specified in the previous settings, but it is possible to exclude metrics that should be activated immediately except for the primary program metric.
Excluded Metrics: The various metric types you want to be excluded from pending metric consideration.
Job Run At: The time of the day that the system will run the pending metric activation job.
Timezone: The timezone in which the system will run the pending metric activation job.
Note: Clicking on any setting in the Pending Metrics Handling collection will enable you to begin setting up your configuration.
1. Click the Enabled setting (or any listed setting below the program setting); this will bring up the Pending Metric Handling pop-up:
2. Set each field below:
- The Enabled toggle is set to Off by default. Click the toggle to On.
- For the Effectivity toggle, select either Immediately or Scheduled.
- If Scheduled is selected, the following additional fields are displayed:
- Policy start: Choose the start date and time for the scheduled job
- Timezone: Choose the time zone for the scheduled job
- If Scheduled is selected, the following additional fields are displayed:
- From the Days Pending field, select the timeframe (1 - 30) desired.
- From the Included Activity Types field, Purchase is selected and cannot be de-selected. You may add one or more activity types.
- In the Excluded Metrics field, select any metric(s) that you don’t wish to include for pending points. Note that the system requires the primary program metric to always be put into pending status when the feature is enabled, so that metric cannot be excluded.
- In the Job Run At field, pick the time you wish to have the pending metric activation job run. This job triggers the activation of pending points that are due that day.
- Select the Timezone for which you want the system to run the pending metric activation job.
Note: When the Enabled toggle is On, the admin user can update the other settings in the pop-up. When the toggle is Off, these other settings are disabled.
Note: The system only allows future scheduling; it is not possible to set a date in the past.
3. Click Save.
Updating settings after initial configuration
Navigate to Program > Settings > Program Settings and locate the Pending Metrics Handling program setting. Click on any setting to bring up the Pending Metric Handling pop-up:
1. Disable pending points: Toggle the Enabled switch to Off. This action will display a message indicating that all pending metrics will be activated during the next run of the activation job. Please note that the daily activation job must run one more time to process any remaining pending metrics, after which it will no longer run (unless the feature is re-enabled).
2. Change the effective start date: Change the Policy Start date to a new date in the future or optionally, select the Immediately effectivity toggle. Note that this will work only if the feature wasn’t configured to start immediately and the scheduled start time hasn’t passed.
3. Change the duration of the pending metrics: In the Days Pending field, change the number to a new number between 1 - 30. This will change the number of days to activate the next activity processed. Note that changes to the Days Pending value will be applied on a go-forward basis only; the new setting will not change the activation date of activities already processed.
4. Change activity types to be processed: Purchase cannot be removed; you may only remove or add other activity types. Note that changes to the Included Activity Types setting will be applied on a go-forward basis only; the new settings will not change activities already processed.
5. Change metrics that the system calculates pending metrics for: Update the Excluded Metrics field by adding or removing any non-primary metric. The system will accrue pending metric value for all included activity types except those specified in the excluded metric setting. Note that changes to the Excluded Metrics setting will be applied on a go-forward basis only; the new settings will not change metric handling for activities already processed.
6. Change the time or timezone for the daily activation job runs: Update the Job Runs At field and/or the Timezone setting.
Re-enabling pending points after being disabled
1. Simply set the Enable toggle to Yes. All settings will begin from the default state and prior settings will not be displayed.
2. If re-enabled before the last daily activation job runs, you won’t be able to re-enable the new pending metric policy. You must run the daily activation job one last time.
3. If you would like to run the activation job immediately, navigate to Admin > Jobs > Scheduled Jobs and locate your daily activation job. Click on the arrow in the upper right of the screen to do so.
Viewing pending points and activity
To view pending metrics awarded to a member, system users can either navigate to CSR > People > Summary (see the Metrics Summary panel), or go to Members > Members > Metrics (see the Pending Total column in the Metrics panel).
Metrics summary panel
To see the metrics summary panel, navigate to CSR > People > Summary.
Pending total column
To see the pending total column in the metrics panel:
1. Navigate to Members > Members > Metrics.
2. A column entitled Pending Total will reflect any pending metrics that have accrued and are not yet activated, less any returns (see note on returns below).
Note on returns: The Return API is planned for an upcoming release. If activating Pending Metrics before the Return API is available, any pending metric accrued by a member will be activated as there is no way to register a return without the planned API.
Example: A purchase accrues 250 pending points. The customer makes a return of 100 points. The Pending Total column would then indicate 150 pending points before activation (250 less the return of 100). Upon activation, the Pending Total will then be 0, and the Earn Total would increase by 150. For more information on how returns work, please see this section.
Note: Earn Total in this context means the metric value activated for a member and eligible to be redeemed later.
3. Under the Activities section, click into the activity detail view to view an activity that has been processed to award pending metric credit. You will see the pending metrics that have been accrued, returned, and the activation date.
How the system activates pending metrics
Each day at the specified time, the system will run a metric activation job to evaluate the pending metric value due to be activated that day for each program member. For any pending metrics that should be activated, the system will generate a Metric Activation activity for the total amount of pending metrics to be activated that day.
Note that for any activity that accrues pending metrics that occurs on the same day, one metric activation activity will be generated.
Example when using a 30-day pending points period:
10/14/2024 1 p.m. UTC Purchase Activity: Pending metrics accrued: 20
10/14/2024 3 p.m. UTC Purchase Activity: Pending metrics accrued: 50
10/14/2024 8 p.m. UTC Purchase Activity: Pending metrics accrued: 10
On 11/15/2024 12 a.m. UTC, the system will activate a total pending metric value of 80, representing the sum across the purchases from 30 days previously.
Note: Any tier calculations or expirations will take effect only after the pending points have become activated.
Return handling with pending metrics
Currently, Pending Metrics do not consider returned items from prior purchases when determining how to activate pending metric value. However, a Return API will be released in early 2025, and when that is available, the system will deduct accrued pending metric value if the return is linked to a purchase where metrics have not yet been activated. This will prevent activating metrics for any portion of a purchase that a customer returns. Again, this behavior is not currently supported so ALL pending metrics will be activated regardless of any return behavior.
More information regarding how the system adjusts pending metrics to activate based on returned items will be provided when the Return API is released.
