Metafields & data storage reference

DollarBack stores its operational data directly on Shopify resources as metafields. This page lists every namespace and key the app writes to customers and orders, so you can consume them from Shopify Flow, integrations, exports, or your own code.

This is the app's live operational data, not a scratch area. Reading it is always safe; editing it by hand can desync the app. The one supported write path is the owed-balance editor described in Admin blocks on the customer & order pages. For everything else, change data through the app or the Merchant API.

Customer metafields

Namespace & key	Type	What it stores
dollar-cashback.balance-adjustments	json	Store credit the customer owes you, per originating order (see below). Powers the "Store credit owed" admin block and is drawn down from future cashback.
dollar-cashback.customer-data	json	Internal per-customer program state, such as birthday reward scheduling.
dollar-cashback.birthday	date	The birthday collected by the birthday program, as YYYY-MM-DD.
dollar-cashback.earned-coupons	json	Append-only list of reward codes issued to this customer.
db-referral.code	string	The customer's referral code; how a redeemed code is mapped back to its referrer. See Referral codes & bulk sync.
dollarback-tiers.customer-tier	string	The customer's assigned loyalty tier, written by tier sync. See Sync tiers to customers.

Shape of balance-adjustments

The value is an array with one entry per debt, each carrying its own audit trail:

[
  {
    "orderId": 6234567890,
    "originalDebitAmount": 12.5,
    "currency": "USD",
    "remainingAmount": 4.5,
    "transactions": [
      { "type": "admin_override", "creditAmount": 8, "currency": "USD", "timestamp": "..." }
    ]
  }
]

The engine only cares about the per-currency sum of remainingAmount: that total is deducted from the customer's next cashback before it is credited. Manual changes made in the admin block are appended as admin_override transactions; debts created from the customer page (rather than a clawback) use orderId: 0.

Order metafields

DollarBack writes to every order it processes; an order with none of these metafields simply had no DollarBack activity. These fields feed the "DollarBack summary" admin block on the order page.

Namespace dollar-cashback

Key	What it stores
cashback-details	The full calculation detail for the order, including pending credits with their status and the applied tier multiplier.
store-credit-given	Display amount of cashback issued for the order.
store-credit-used	Store credit the customer spent paying for the order.
no-credit-reason	Why the order earned nothing, when it didn't.
discount-code-rewards	Earn-side reward codes issued from this order, each with its status (e.g. revoked).
order-edit-history	One entry per cashback recalculation after an order edit.

Namespace dollar-referral

Key	What it stores
referral-details	The referrer this order was attributed to (name, email) and the commission paid (cashbackGiven, currency).
referral-edit-history	One entry per referral-reward recalculation after an order edit.

Using the data

• Shopify Flow: metafields make good conditions; the tag-by-tier example in Sync tiers to customers reads dollarback-tiers.customer-tier, and Flow triggers/actions for credit itself are covered in Shopify Flow triggers & actions.

• Storefront: don't read metafields from Liquid for balances; use the Storefront window API, which returns live values.

• Backend: for reads and writes with guarantees, use the Merchant API instead of mutating metafields.

Related articles

• Admin blocks on the customer & order pages

• Merchant API: keys & endpoints

• Storefront window API

• Refunds, cancellations & order edits