On this page
A normalization layer translates source data into the facts a reward rule can use. It should preserve meaning, including uncertainty. When a missing amount becomes zero or an unavailable customer field becomes “customer has no value,” the adapter has made a business assertion that the source never established.
Imagine a hypothetical order containing an eligible item whose amount is absent from the selected response. A permissive parser converts the missing value to 0. The reward engine then produces a zero result and reports that evaluation completed. The correct technical result is that a required input remains unknown.
Define required types and explicit unknown states
Write an input contract for each field used by the approved evaluation. Include its type, source meaning, whether it is required and the states that can prevent interpretation. A useful contract distinguishes present, absent, restricted, malformed and not applicable where those differences affect the workflow.
Shopify’s protected-customer-data requirements can affect access to relevant fields. A field unavailable to an app does not establish that the customer lacks the underlying attribute. Shopify protected customer data
For the hypothetical amount, the normalized representation should carry a known value with currency or an explicit unknown reason. Do not use one primitive numeric field whose default is silently interpreted as a valid amount.
A proposed type table is:
| Input | Valid representation | Unknown or invalid example |
|---|---|---|
| Purchase identifier | Opaque source reference in trusted shop | Missing or wrong resource type |
| Relevant amount | Exact decimal or minor-unit value plus currency contract | Absent, malformed or unsupported currency |
| Quantity | Valid quantity under the source contract | Null or incompatible unit meaning |
| Recipient field | Authorized value with documented purpose | Restricted or unavailable |
| Campaign reference | Valid candidate resolved in trusted scope | Unknown campaign or conflicting version |
| Source time | Parsed instant with defined meaning | Ambiguous local string |
These are original internal design categories, not published RebateCardX fields.
Avoid a catch-all default function that converts every false-like value to zero or an empty string. A valid zero, an empty string and a missing property can have different meanings. The adapter should preserve those differences until the approved rule or data contract explicitly resolves them.
Requiredness belongs to the task. A missing optional display label may allow evaluation to continue. A missing amount required by the formula may block it. The normalization result should identify which dependent task cannot proceed, rather than rejecting the entire purchase without explanation.
Preserve currency and identifier meaning during transformation
Money needs an amount, currency and unit contract. Do not assume that every source field uses the same representation or that every currency follows the same minor-unit convention. The adapter must follow the documented field semantics for the selected API and program.
For a hypothetical USD fixture, a source contract might express 1250 as minor units, meaning $12.50. Another field might contain the decimal string 12.50. If the adapter treats both as display-unit numbers, one becomes a thousandfold larger. The fixture should make that interpretation explicit rather than rely on the field name looking familiar.
Use exact decimal or integer-minor-unit handling appropriate to the contract. Binary floating-point arithmetic can introduce representation issues in money calculations. The normalization layer should establish a precise value; the approved formula then applies its own defined rounding rule at the correct stage.
Identifiers also require types. A product identifier, variant identifier, order identifier and award reference are not interchangeable because each is a string. Preserve their resource meaning and trusted shop association. A normalizer should reject an order slot containing a product reference rather than letting a later lookup fail ambiguously.
An original normalization sketch is:
normalize_amount(source_field, documented_unit, currency):
if source_field is absent:
return Unknown(reason=required_value_absent)
if currency is not_established:
return Unknown(reason=currency_unavailable)
if source_field cannot_be_parsed_exactly:
return Invalid(reason=malformed_amount)
return Known(exact_value, currency, documented_scope)
This is illustrative pseudocode. It describes a proposed internal contract, not a vendor API response.
Preserve amount scope with the value. A correctly parsed $100 can still be the wrong input if it represents the whole order when the rule requires eligible merchandise only. The source mapping should state which line, allocation or aggregate the value represents, while leaving formula selection to the approved campaign design.
A difficult case is a quantity change after purchase. The original quantity, current quantity and returned quantity can describe different facts. Do not normalize all of them into one generic quantity field without recording which meaning the reward rule needs. The adapter should expose the relevant facts accurately rather than decide the return policy through naming shortcuts.
Reject or quarantine records that cannot be interpreted safely
The normalized result should be reviewable. A record can preserve the purchase identity and established fields while marking one required input unresolved. This is more useful than either crashing the entire worker or inventing a default that lets the job appear complete.
For the hypothetical order, the quarantine record can say: purchase identity established, currency USD established, eligible amount unavailable, evaluation blocked at input normalization. It should include the source version and safe field path needed for investigation, without copying unnecessary customer data into the error queue.
Use a fixture matrix that challenges meaning:
| Source condition | Expected normalized outcome |
|---|---|
| Valid zero amount | Known zero under the documented scope |
| Amount property absent | Unknown, not zero |
| Amount string malformed | Invalid with a safe diagnostic |
| Currency missing | No currency guess |
| Restricted recipient field | Unavailable under access context, not proof of absence |
| Identifier has wrong resource type | Rejected mapping |
| Valid amount from wrong scope | Mapping failure or explicit separate field |
| Quantity meaning ambiguous | Reviewable unresolved input |
Run the fixtures through the exact adapter used for production. A separate test parser can accidentally validate a cleaner contract than the real code implements. Compare the resulting normalized state and verify that blocked inputs produce no consequential provider operation.
For a filled example, use three synthetic records with the same purchase shape: one has a known $0 amount, one has a known $12.50 amount and one lacks the amount. The expected results are three distinct states. If the first and third produce identical normalized output, the adapter is erasing information the downstream decision needs.
Record how a quarantined case resumes. When the missing field becomes available through authorized access, the service should normalize the same purchase reference again and preserve its operation history. It should not create a new purchase merely because the earlier attempt could not establish every field.
Inspect dashboards and support labels as well. A technical “input unavailable” state should not be presented as a final customer rejection. The display mapping must preserve the distinction between a business outcome and an inability to determine that outcome.
The completed contract gives every required input a type, source meaning and uncertainty state. It prevents the normalization layer from quietly writing its own reward rules through defaults, while giving the rest of the integration a precise explanation of what is known and what still needs evidence.
Version the normalization contract itself. A downstream service should know whether a field contains an established value or an explicit unknown representation under the current schema. If that representation changes, update its consumers deliberately rather than relying on a truthiness check that can turn the new state object into an accidental approval.
Request technical access to align the Shopify-to-reward data contract.
Source references
This guide is general information, not financial, legal, tax or regulatory advice. Eligibility, card availability, permitted use and responsibilities depend on the applicable offer and card terms.
