Skip to content

Systems and records

Retail loyalty exception dataset: what transaction rows miss

By SourceX Editorial · Reviewed by Noah Loul ·

10 sections

Short answer

Loyalty exception histories show the decisions transaction rows leave out: why an associate added or removed points outside the earning rules, which promotion or policy version applied, who approved it, what the order, stock and account state was, and whether the customer outcome held. A retail loyalty exception dataset links each manual adjustment, reversal override or goodwill credit to that evidence and labels it with one consistent guide.

Provenance trail

Retail loyalty exception

This page covers retail loyalty exception dataset: what transaction rows miss.Illustrative

Key takeaways

  • A loyalty transaction row records points; the exception history records the judgment behind them.
  • Loyalty platforms often keep a reason as optional free text and no approver at all, so the decision has to be rebuilt from linked records.
  • The valid action depends on the promotion, item, fulfillment and account state at decision time, so snapshot that state rather than joining today's.
  • Label rationale from a closed code list, approval from evidence only, and outcome over a fixed window.
  • Strip member identifiers from every linked table and free-text field, and have counsel confirm the program terms allow the use.

What do loyalty exception histories reveal that transaction rows omit?

They reveal the judgment. A transaction row says a member gained or lost a number of points on a date. The exception history says why someone overrode the earning rules, which promotion or policy version they relied on, who allowed it, what the order and stock looked like at that moment, and whether the customer stayed resolved afterward.

Loyalty platforms record the arithmetic well and the reasoning poorly. In Square's published API specification, the AdjustLoyaltyPoints endpoint is meant only for manual adjustments, the resulting event type is ADJUST_POINTS, and the adjustment record carries a points value and a free-text reason of up to 3,500 characters. Only the points value is required, so an archive can hold thousands of manual changes with an empty reason field.

Salesforce Loyalty Management works at the level of the transaction journal: its Adjust Points action changes points for a specified program member or journal transaction, and journal types group transactions into categories such as accrual and redemption. Either way, the decision that produced the adjustment usually lives somewhere else: a service ticket, a store manager's note, a promotion calendar, an order system. A retail loyalty exception dataset is the work of joining those pieces back together and labeling them consistently.

Which loyalty events are exceptions, and which are routine bookkeeping?

Treat an event as an exception when a person or a non-standard rule changed the balance, and as routine when the configured earning or redemption rules did it unaided. That one test keeps the dataset focused on decisions instead of on ledger noise.

Refunds are the hardest boundary because automation already handles many of them. Square's help center says the effect of a refund on points depends on both the program type and the refund type: a partial item refund in a per-item program removes the points that item earned, while a custom refund amount removes none. Salesforce documents the mirror pattern for reversals, where reversing an accrual debits the earned points and reversing a redemption credits the redeemed points back. When a person then corrects what the automation did, that correction is the exception.

Which loyalty events are exceptions, and which are routine bookkeeping?
Loyalty eventRoutine whenException whenEvidence to pull
Point accrualPoints match the program rule for the order linesPoints added for lines the rule excludes, or at a different rateOrder lines, item categories, rule version in force
Promotion pointsPromotion was active and the order qualifiedPoints granted after the promotion ended or for a non-qualifying itemPromotion record, status history, qualifying items
Refund or return reversalAutomatic reversal follows the platform ruleA person overrides the reversal or reverses more or less than the ruleRefund type, return lines, reversal record
Manual adjustmentNever routine by definitionAny goodwill, correction or recovery credit or debitReason text, operator, linked ticket or note
Reward void or deletionCustomer cancels before redeemingReward voided after a dispute, or points restored after a failed redemptionReward record, order, contact history
Points expirationExpiry follows the program scheduleExpired points reinstated on requestExpiration schedule, reinstatement adjustment
Negative balanceNot allowed by defaultA subtraction pushed the balance below zero by choiceAdjustment flag, refund or exchange that caused it

Which item, rule or inventory change alters the valid loyalty action?

The valid action depends on linked state, not on the loyalty row alone: the order line, the item's eligibility, the promotion's status at the time, the stock position that forced a substitution or split shipment, and any change to the member account. Capture each as it stood when the decision was made, not as it stands today.

Promotions are the clearest example. Square models a loyalty promotion with a status of ACTIVE, SCHEDULED, ENDED or CANCELED, optional qualifying item variations and categories, and a trigger limit, and a program can have at most 10 promotions that are active or scheduled at once. A customer who ordered during an active promotion and received the goods after it ended can be owed points under one reading of policy and not another. Without the promotion's status history, an annotator cannot tell a correct goodwill credit from an error.

Inventory and fulfillment matter in the same way. A backordered line that ships later, a substitution with a different category, or a cancellation of part of an order can all change which points were earned. Member identity matters too: Square's specification notes that a loyalty account can currently be mapped to a buyer only by phone number, so a changed or shared phone number can split one person's history or merge two people's, and adjustments made to fix that are exceptions of their own.

  • Order and line identifiers, with the line status at decision time
  • Item and category identifiers as the program saw them
  • Promotion identifier, its status on the order date and on the adjustment date
  • Inventory or fulfillment event that changed the order: backorder, substitution, split shipment, cancellation
  • Member account events: phone change, merge, re-enrollment
  • The program rule or policy document version in force on the adjustment date

What should the exception rationale and approval annotation guide include?

The guide needs one row per labeled field: what to record, the allowed values, which system is the source of truth, and the mistake labelers most often make. The version below is written so a retail team can copy it into a labeling tool as is and adjust the allowed values to its own program.

At a glance

What should the exception rationale and approval annotation guide include

What should the exception rationale and approval annotation guide include?
FieldWhat to recordAllowed valuesSource of truthCommon labeling error
exception_idOne stable identifier per adjustment or overridePlatform event or journal IDLoyalty platformLabeling a whole customer instead of one event
exception_typeWhat kind of override this wasaccrual_override, promo_honor, reversal_override, goodwill, recovery, reinstatement, account_fixLoyalty event plus linked contextCalling an automatic reversal an override
rationale_codeThe single main reason, from the code listOne code from the rationale listReason text, ticket, noteChoosing the customer's claim instead of the reason the associate acted
rationale_evidenceWhere the reason was foundreason_field, ticket, store_note, inferred, noneLinked recordsMarking inferred reasons as recorded
policy_referenceRule or policy version relied onPolicy ID and version, or none_citedProgram configuration, policy libraryUsing today's policy for an old decision
approval_statusHow the change was authorizedauto_rule, within_own_limit, approver_recorded, approval_elsewhere, no_evidencePlatform, ticket, approval logAssuming approval because the change went through
linked_stateOrder, item, promotion, stock and account state at decision timeIDs plus status snapshotOrder, catalog, promotion and inventory systemsJoining current state instead of the historical snapshot
customer_outcomeWhat happened after the adjustmentheld, re-contacted, reversed_again, escalated, unknownContact history, later loyalty eventsClosing the window too early
label_confidenceHow sure the labeler ishigh, medium, lowLabeler judgmentLeaving low-confidence items unflagged
labeler_noteAnything a reviewer must seeFree text, no customer identifiersLabelerCopying names or phone numbers into the note

Rationale codes: one reason per adjustment, applied the same way by every labeler

Pick one primary reason per exception from a closed list, and record secondary reasons separately if you must. A short list that labelers apply the same way beats a long list that splits hairs, because a model trained on inconsistent reasons learns the labelers, not the policy.

Write each code with the evidence it requires and the code it is most often confused with. Then double-label a fixed sample agreed before labeling starts, compare, and turn every disagreement into a clarifying sentence in the guide. Record the guide version on every label so later readers know which wording applied.

Rationale codes: one reason per adjustment, applied the same way by every labeler
Rationale codeMeaningEvidence requiredOften confused with
promo_timingCustomer qualified for a promotion that ended or started around the orderPromotion status history and order datespromo_eligibility
promo_eligibilityItem or category was wrongly treated as qualifying or not qualifyingQualifying item or category list for that promotionpromo_timing
fulfillment_changeBackorder, split shipment, substitution or partial cancellation changed earned pointsFulfillment events on the orderrefund_mismatch
refund_mismatchAutomatic reversal removed too many or too few pointsRefund type and reversal recordfulfillment_change
service_recoveryGoodwill points for a service failure, not owed under the rulesTicket or note describing the failurepromo_timing
account_identityFix after a merged, split or re-mapped member accountAccount change eventsdata_entry_fix
data_entry_fixCorrecting a keying or scanning errorOriginal and corrected valuesaccount_identity
fraud_or_abuse_recoveryPoints removed after misuse was foundInvestigation reference only, no detailsrefund_mismatch

Labeling approval when the loyalty system never stored an approver

Label what the evidence shows, not what policy says should have happened. If no record names an approver, the label is no_evidence or approval_elsewhere, never approver_recorded.

At a glance

Labeling approval when the loyalty system never stored an approver

This matters because many loyalty schemas do not hold the approval at all. Square's adjustment event carries the program, the points and an optional reason; it has no approver field. Approval, where it exists, sits in a point-of-sale employee record, a help desk ticket, an email or a manager's spending limit configured somewhere else. Join those sources by order or ticket number and timestamp, and keep the join method in the record so a reviewer can check it.

Separate two questions labelers tend to merge: was the change authorized, and was it right under policy. A within-limit goodwill credit can be fully authorized and still contradict the written policy, and a model that learns approvals as proof of correctness will repeat the mistake.

  • auto_rule: the platform applied a configured rule; no person decided
  • within_own_limit: the operator acted inside a documented personal limit
  • approver_recorded: a named role approved in a linked record before or at the change
  • approval_elsewhere: approval is referenced but the record itself is not in the dataset
  • no_evidence: nothing links the change to an approval

Illustrative: a late promotion honored after a split shipment

This example is illustrative and not drawn from a real retailer. A member orders three items online during a double-points promotion. One item is backordered; the other two ship at once. The backordered item ships eleven days later, after the promotion ended, and the platform awards base points only for that line.

The member contacts support. The associate adds the missing promotion points with the reason text "promo honored, backorder." A team lead approves in the help desk ticket. Two weeks later the member returns one of the first two items, and the automatic reversal removes points at the base rate rather than the promotion rate, leaving a small surplus.

Labeled with the guide, the first adjustment becomes exception_type promo_honor, rationale_code fulfillment_change rather than promo_timing (the timing problem was caused by the backorder), rationale_evidence reason_field plus ticket, approval_status approver_recorded, and customer_outcome held. The return creates a second record: exception_type reversal_override is not used because no one overrode it, so it is labeled as routine with a reviewer note that the reversal rate did not match the earning rate.

The exception to the method: a fourth record in the same account shows a manual credit with an empty reason, no ticket, and a phone number change the same day. The right label is account_identity with label_confidence low and approval_status no_evidence. Labelers should not guess the story, and a dataset that keeps such records flagged is more honest than one that drops them silently.

Did the fix hold? Checking the customer outcome after the adjustment

Check the outcome over a window that you fix before labeling, because an adjustment that looks resolved on the day can unravel later. The outcome label should come from later events, not from the associate's closing note.

Useful signals are a repeat contact on the same order, a second adjustment on the same account, a reversal of the credit, a chargeback or dispute reference, and the member's later activity. Choose the window to fit your return policy and contact patterns, record it on every label, and mark outcomes as unknown when the window has not closed or the data is missing. An unknown outcome is still a usable record for training the decision; it is not usable for grading it.

Loyalty records to hold back, strip or route to a privacy reviewer

Hold back what identifies members or exposes investigations, and send anything involving incentives tied to personal data to a privacy reviewer before records leave the business. Loyalty data is consumer data first and operational data second.

Phone numbers, emails and member numbers come out or are replaced with consistent tokens, and free-text reasons and ticket notes need the same scrubbing because associates often type names there. Fraud and abuse cases should carry only an investigation reference. Records about employees' own accounts, and categories that reveal health or other sensitive purchases, are usually better excluded than masked.

Loyalty programs are also a regulated form of offer in some places. California's privacy regulations, for example, in section 7016, require a notice of financial incentive that summarizes the offer, explains its material terms including the categories of personal information involved, and describes how to opt in and withdraw. Whether a program's notices and terms permit a new use of member records is a question for counsel on the specific facts. De-identifying the records does not by itself create a right to license them.

  • Remove or tokenize member identifiers consistently across all linked tables
  • Scrub reason fields and ticket text for names, contact details and payment references
  • Exclude employee-account adjustments and sensitive purchase categories
  • Keep fraud records to an outcome and a reference, never investigation detail
  • Document every exclusion rule in the dataset's documentation so buyers know what is missing

Turning a loyalty exception archive into a licensed dataset

A labeled exception archive is most valuable with its documentation: the guide version, the code list, the outcome window, the join methods and the exclusions. The datasheet approach proposed by Gebru and colleagues asks dataset creators to document motivation, composition, collection, labeling and recommended uses, and those headings fit a loyalty exception dataset well.

Retail loyalty records can be licensed through SourceX, which handles rights review, contracting, preparation, delivery and payment for selected business records. A retailer can begin with a short company assessment and upload nothing. No member record is delivered before the retailer approves the scope and terms and signs, and SourceX's later rights to use, sublicense or distribute the de-identified result come only from that signed text.

Frequently asked questions

What is a retail loyalty exception dataset?

It is a set of loyalty events where a person or a non-standard rule changed a member's points, each linked to the order, promotion, inventory and account state at the time, and labeled with a reason, an approval status and a customer outcome. Routine accruals and redemptions that followed the program rules are excluded or kept only as context.

Why not just train on all loyalty transactions?

Routine transactions teach the earning rules, which are already written down. The exceptions show how staff handle the cases the rules did not anticipate, which is the judgment an AI assistant or agent would need to support. Mixing the two without a label hides the decisions in ledger volume.

What if the reason field is empty?

Look for the reason in linked records such as a help desk ticket or store note and mark it as inferred, not recorded. If nothing explains the change, label the rationale as unknown with low confidence rather than guessing. Those records still show where documentation breaks down.

How many labelers does the annotation guide need?

At least two for the agreement sample, plus one adjudicator who owns the guide. The size of the double-labeled sample is a choice to fix in advance and record with the dataset; what matters most is that disagreements change the guide wording and the guide version is stored on every label.

Can loyalty member data be licensed for AI at all?

Sometimes, depending on the program terms, privacy notices, the laws that apply and how well the records are de-identified. Those questions need counsel on the specific facts. De-identification reduces privacy risk but does not by itself give a company the right to license the data.

Sources

  • Square's API specification limits AdjustLoyaltyPoints to manual adjustments, lists ADJUST_POINTS among loyalty event types, makes the adjustment reason optional free text up to 3,500 characters, defaults allow_negative_balance to false, caps a program at 10 active or scheduled promotions with statuses ACTIVE, SCHEDULED, ENDED and CANCELED, and maps loyalty accounts to buyers only by phone number. Source
  • Square's help center says the impact of a refund on loyalty points depends on both the program type and the refund type. Source
  • Salesforce Loyalty Management's Adjust Points action adjusts points for a specified program member or journal transaction. Source
  • Salesforce documents that reversing an accrual debits the member's earned points and reversing a redemption credits the redeemed points back. Source
  • Salesforce's JournalType object represents the category of loyalty transactions, such as accrual and redemption. Source
  • California's CCPA regulations require a notice of financial incentive summarizing the offer and its material terms, including the categories of personal information involved, how to opt in and the right to withdraw. Source
  • Datasheets for Datasets proposes documenting a dataset's motivation, composition, collection process, labeling and recommended uses. Source

See if your company qualifies

A short company assessment. No data uploads are needed.

See if your company qualifies