On this page
A cart reference can help a backend recognize which campaign a shopper encountered. It cannot prove that the shopper earned the offer, and it should never carry the authority to choose a reward amount. The safe design treats browser-supplied metadata as a claim that needs validation against the actual purchase.
In a hypothetical running store, a campaign page introduces offer RUN-AUTUMN-4. The shopper adds shoes to the cart, then later adds socks from another page. The integration wants the final order to retain the campaign reference without confusing it with a discount code, a personal claim token or an instruction to issue a card.
Choose a non-sensitive campaign reference format
Use a stable opaque reference whose only purpose is to locate an approved campaign record. It can be readable enough for support to recognize, but it should not encode a customer email, a secret or an amount that the backend will trust. A value such as RUN-AUTUMN-4 is a label, not authorization.
Shopify’s Ajax Cart API supports cart attributes and line-item properties. Those mechanisms have different scopes, so choose the one that matches the information being carried and verify its behavior on the store’s purchase paths. Shopify Ajax Cart API
An order-wide campaign context may fit a cart-level reference. A reference tied to one specific merchandise line may need a line-level representation. Do not copy the same campaign into every line merely to make it visible everywhere; that can create conflicting or duplicated context when lines merge, split or change.
For the fictional offer, the proposed contract uses one cart-level candidate campaign reference plus a publication version. The backend still determines which purchased lines are within the campaign. This keeps the reference from becoming a second, unofficial product eligibility list maintained in the browser.
Write the format rules explicitly:
| Property | Proposed rule |
|---|---|
| Meaning | Candidate campaign lookup reference |
| Allowed content | Bounded plain-text identifier |
| Sensitive data | None |
| Authority | Untrusted until server validation |
| Missing value | Follow the approved campaign matching rule |
| Conflicting values | Resolve through a documented precedence rule |
| Retention | Keep only as needed for the approved purchase record |
The table describes an original integration contract, not a required Shopify field name or RebateCardX schema. The exact storage location must be checked against the current API and integration.
Avoid naming a field approved_reward when it merely stores a marketing reference. Names influence how future developers interpret data. A field called candidate_campaign_reference makes its limited role visible and reduces the chance that another service treats it as a final decision.
Preserve the reference through supported cart paths
Map how the reference enters, changes and leaves the cart. A landing page may set it when the shopper begins a campaign journey. An ordinary product page may leave it unchanged. A second campaign page may replace it, preserve the first reference or require an explicit selection. That precedence is a business rule that the implementation must receive, not invent.
For the running store, suppose the approved rule is that the campaign attached at the final qualifying purchase controls, subject to its validity window. The browser can carry the latest candidate, but the backend must still establish that the candidate was valid for the actual order. A stale cart reference cannot revive a withdrawn offer by itself.
Test updates as operations with observable results. After writing the reference through the supported cart interface, read the resulting cart state and confirm what was persisted. Do not assume a successful button click means the metadata write completed before navigation to checkout.
A race can occur when a customer selects “buy now” while an asynchronous metadata update is still in flight. The integration needs a reviewed design for that path: an earlier supported attachment point, a backend campaign lookup that does not depend on the late write, or a clearly documented unsupported route. Adding an arbitrary delay to the button is not proof of continuity.
The Storefront API has its own cart workflow for headless implementations. Do not assume an Ajax Cart API pattern can be copied unchanged into a headless client. Verify the selected cart contract and the resulting order mapping in the actual architecture. Shopify Storefront API cart workflow
Preserve ordinary cart behavior. Updating a campaign reference must not accidentally erase unrelated attributes, modify quantities or overwrite a buyer’s personalization property. Review how the chosen operation handles existing data, and test a cart containing other app-managed fields. A narrow reward handoff should remain narrow when it shares the cart with other integrations.
Validate the reference against an authoritative campaign record
When an authorized order reaches the backend, treat the carried value as one input to campaign resolution. The backend verifies the trusted shop, campaign existence, applicable version, publication or purchase timing rule, and the actual order facts required by the approved offer.
An original decision sketch is:
candidate = read_non_sensitive_campaign_reference(order)
if candidate is missing:
use_approved_missing_reference_rule()
else if candidate has_invalid_format:
retain_safe_diagnostic_and_request_review()
else:
campaign = lookup_within_trusted_shop(candidate)
if campaign cannot_be_established:
record_unresolved_campaign_context()
else:
evaluate_actual_order_against_approved_campaign(campaign)
The pseudocode does not prescribe rejection for every missing reference. Some programs can determine eligibility from the purchased item and timing without any campaign metadata. Others require a specific published participation path. The backend must follow the approved rule, not a default chosen because it is easy to code.
The fictional test set should include a valid reference, a reference from another store, an expired campaign, an altered value, an absent value and two competing campaign references. For each, record the resolved campaign or the specific review state. “Job succeeded” is too weak if the system silently chose the wrong offer.
A difficult case is a valid reference copied from one shopper’s cart to another. Because the reference is deliberately non-secret, the design must assume it can be copied. If the offer requires a restricted audience or unique entitlement, that restriction needs a separate authorized check. Hiding the campaign identifier does not create that check.
Keep the carried value and the resolved authoritative campaign distinct in the audit record. For example, store that the browser supplied RUN-AUTUMN-4, the server resolved approved version 4 for the trusted shop, and the purchase was evaluated under that version. If the two differ, retain the reason rather than silently replacing the input.
Finally, verify the end-to-end handoff using a permitted test purchase. Inspect the original cart context, the final order representation and the backend’s resolved campaign. The completed contract should show exactly what the reference helps establish and which decisions remain with the approved reward process. That makes cart metadata useful without giving it authority it does not possess.
A useful handoff artifact is a single filled trace for the running-store test. Record the candidate at cart creation, the value after the socks are added, the value present on the completed test order and the campaign version resolved by the backend. Add a second trace where another campaign page is visited before checkout. Compare the observed result with the approved precedence rule. This is more informative than testing only whether the metadata field exists: the field can survive perfectly while holding the wrong campaign. The trace also shows which component owns a correction when the value changes unexpectedly.
Keep the accepted precedence rule beside the trace, so a later campaign owner can distinguish an intentional replacement from an accidental cart overwrite.
Request technical access to review supported campaign-reference handoffs.
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.
