Achievements troubleshooting.

Straight answers first, operator tooling after.

Common questions

What counts as a loyalty day?

One calendar date, in your business timezone, on which the member earned something real at your business: points from a purchase or credit, a redeemed point code, a store-order earn, a stamp, a redeemed reward or voucher, or a prepaid pass action. Everything on one date counts once. See What a loyalty day is.

Deliberately excluded: welcome and other bonuses, member-to-member transfers, deductions, refunds, corrections and voids, expiry entries, and rewards delivered by the achievements program itself. A reward can never feed the next reward. One nuance: when a member later uses a voucher or pass they received as an achievement reward, that use is a real customer action and does count.

Why did a day not count?

The usual reasons, in order of likelihood:

• The member already had a loyalty day on that date. A second action on the same date changes nothing.
• The action was an excluded type from the list above.
• The member is a guest without a linked email. Achievements only track registered members; activity starts counting once they register.
• The action was rolled back. A voided purchase, a reversed stamp, or an undone pass action removes its contribution, and an achievement that only existed because of it is corrected.
• The program was paused, or the plan lost the feature, at the time of the action.

Which timezone and week start apply?

Your business timezone (from your business profile) decides which date an action belongs to. The program's Week starts on setting (Sunday or Monday) decides the weeks behind the weekly-run milestones. Changing the timezone affects future activity only; changing the week start applies from now on and never breaks an active run. See The calendar.

What happens to old activity when I enable the program?

The history import recognizes it: achievements your customers' history already earned appear with their historical dates. History earns achievements, never rewards, and never sends messages. The import runs on its own, survives a closed browser, and shows its progress on the page. See What happens to old activity.

When do rewards start, expire, stop, or fail?

A reward starts paying when you attach it (or on its Available from date), stops at its Until date or when its grant cap fills, and never pays for achievements earned before it existed. A delivery that keeps failing waits for you under Needs attention with a plain reason and a Try again button. Members with an undelivered reward see "Reward on its way", never an error. Full rules: Rewards and limits.

What happens when I pause, downgrade, change timezone, or delete a member?

• Pause: everything earned is kept, rewards on their way still arrive, no new progress counts. See Pausing and resuming.
• Downgrade (the plan loses the feature): same keep-everything rule. Members keep their achievements and see their history; new progress stops counting; the partner page shows the upgrade state. A history import that was still running waits, and continues when the feature returns.
• Timezone change: future activity is dated in the new timezone; recorded days keep their dates. When a program is active, the business settings page shows this impact before you save, and the change is recorded in the achievements activity log.
• Member deletion: both privacy paths remove achievement data with the rest. Removing a member's data for one business deletes their achievement records at that business; a full account deletion removes them everywhere. The member data export includes achievement data.

What does the member see?

Their own progress and earned collection per business, one celebration per earning moment, and one notification per earning moment, with email following their own loyalty-updates preference. Never another business's data, never delivery errors. See Member experience.

Which reports, segments, API endpoints, and support actions exist?

• Insights on the achievements page: members with an achievement, awards in the last 30 days, members on a weekly run, members close to a milestone, and voucher and pass reward usage.
• Member list: an achievements column shows each member's earned count.
• Segments: two rules, "Has achievement" and "Achievement progress at least (%)", for targeting the member list and campaigns. See Member segments.
• Agent API: three read-only endpoints for the program, a member's progress, and the member's own view. See the endpoint reference.
• Activity log: program changes (enable, pause, resume, week change, rule and reward edits, retries) are recorded under the achievements category.
• Support actions: the operator can void a single achievement as an audited action. It lives in the admin area, on a member's achievements view reached from the achievements column on the admin member list. See Voiding a fraudulent achievement below.

How do I repair a failed reward delivery or a stalled history import?

Rewards: fix the cause on the reward deliveries panel, then Try again. Imports: they resume on their own; the Continue import button pushes one batch through by hand. If something still looks stuck, the operator tools below cover it.

Operator tools

Voiding a fraudulent achievement

When an achievement was earned fraudulently, an operator can void it. Open the member in the admin member list and follow the Achievements column to that member's achievements view. It lists every achievement the member earned, grouped by business, with the earned date, origin, and reward state. Each active row has a Void control.

Voiding asks for a short reason and keeps it. What it does:

• Hides the achievement from the member. It leaves their page, wallet, live feed, notifications, insights, and the API at once.
• Keeps the audit record. The row stays on this view, marked voided, with the reason, the operator, and the date. Nothing is deleted.
• Blocks re-earning. The member cannot earn that same achievement again; the voided record holds its place.
• Does not touch a delivered reward. A reward that already reached the member is not removed. If it should be taken back, correct the underlying product (points, stamps, voucher, or pass) through its own flow, the same way you would for any other correction.

The action records an achievement voided entry in the activity log with the operator, the business, the achievement, and the reason. It is admin-only, and voiding an already-voided achievement does nothing.

Health Center rows

The admin Health Center watches achievements install-wide:

• An Achievement rewards check in the services list: green when nothing is waiting, a warning when a reward has waited longer than expected or a history import stalled or failed, and critical when any delivery failed for good.
• An Achievement reward delivery panel with the numbers behind it: rewards waiting and rewards that failed, how long the oldest has waited, active history imports and when the oldest was last active, and stalled or failed imports, plus the last delivery run's result.
• A Deliver pending rewards now button that delivers a small batch (up to 20 rewards) at once. Safe to press as often as you like; deliveries can never duplicate.

Delivery runs every minute with cron, rides along on normal site activity without cron, and can always be run from this panel by hand.

The repair command

For anything the buttons do not cover, one artisan command rebuilds a partner's achievement records from the source ledgers:

php artisan achievements:reconcile --partner=<uuid>
php artisan achievements:reconcile --partner=<uuid> --member=<uuid>
php artisan achievements:reconcile --partner=<uuid> --from=2026-01-01
php artisan achievements:reconcile --partner=<uuid> --dry-run

• --partner (required): the business to repair.
• --member: limit the repair to one member.
• --from: only scan ledger rows on or after this date. This bounds the scanning work on large histories; days and achievements recognized earlier are preserved, never deleted by a narrower scan.
• --dry-run: report what would change (new events, days, progress rows, awards per achievement) without writing anything.

The command is resumable and repeat-safe: it picks up where an interrupted run stopped, and re-running a completed range changes nothing. Like the live program, repairs recognize history without sending rewards or messages, and they refuse guests: a member without a linked email has nothing to reconcile until they register.

Stalled and waiting imports

A history import that stopped partway (a crashed request, a killed process) shows as stalled in the Health Center and recovers on its own: the background delivery run advances it, the partner's Continue import button advances it, and the repair command finishes it. State lives in the database, so nothing is lost in between.

An import for a partner whose plan lost the feature waits instead of failing. It resumes when the feature returns. An import that stopped after repeated errors shows as failed in the Health Center; run the repair command for that partner to finish it.

Log lines

Application log entries for achievements carry identifiers, counts, durations, and fixed error codes (resource_missing, resource_inactive, resource_foreign, member_missing, config_invalid, delivery_error), never member content. Partner-visible changes land in the activity log under the achievements category.

Related topics

• Partner setup: Statuses, the calendar, and the history import
• Rewards and limits: Delivery, retries, and failure reasons
• Health center: The install-wide diagnostics page