> For the complete documentation index, see [llms.txt](https://help.dollarlabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.dollarlabs.io/dollarback-store-credit/developer-tools/metafields-and-data-storage.md). # 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. {% hint style="warning" %} 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](/dollarback-store-credit/analytics-data-and-account/admin-blocks-customer-and-order-pages.md). For everything else, change data through the app or the [Merchant API](/dollarback-store-credit/developer-tools/merchant-api-keys-and-endpoints.md). {% endhint %} ## 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-store-credit/referral-program/referral-codes-and-bulk-sync.md). | | `dollarback-tiers.customer-tier` | string | The customer's assigned loyalty tier, written by tier sync. See [Sync tiers to customers](/dollarback-store-credit/loyalty-tiers/sync-tiers-to-customers.md). | ### Shape of `balance-adjustments` The value is an array with one entry per debt, each carrying its own audit trail: ```json [ { "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](/dollarback-store-credit/loyalty-tiers/sync-tiers-to-customers.md) reads `dollarback-tiers.customer-tier`, and Flow triggers/actions for credit itself are covered in [Shopify Flow triggers & actions](/dollarback-store-credit/integrations/shopify-flow-triggers-and-actions.md). * **Storefront**: don't read metafields from Liquid for balances; use the [Storefront window API](/dollarback-store-credit/developer-tools/storefront-window-api.md), which returns live values. * **Backend**: for reads and writes with guarantees, use the [Merchant API](/dollarback-store-credit/developer-tools/merchant-api-keys-and-endpoints.md) instead of mutating metafields. ## Related articles * [Admin blocks on the customer & order pages](/dollarback-store-credit/analytics-data-and-account/admin-blocks-customer-and-order-pages.md) * [Merchant API: keys & endpoints](/dollarback-store-credit/developer-tools/merchant-api-keys-and-endpoints.md) * [Storefront window API](/dollarback-store-credit/developer-tools/storefront-window-api.md) * [Refunds, cancellations & order edits](/dollarback-store-credit/spending-store-credit-and-rewards/refunds-cancellations-and-order-edits.md)