Financial semantics

This page is the accounting contract shared by checkout, orders, refunds, customer balances, POS, and analytics. If another page or screen uses a term differently, treat that difference as a defect rather than inventing a second definition.

Caution

Sellerlane operational reports are not a general ledger, bank statement, or tax return. They explain commerce activity. Reconcile gateway settlements, cash, tax filings, and accounting-system entries separately.

Money and currency

• Every monetary amount is stored as an integer number of the currency’s minor unit. For INR, 10000 means ₹100.00. Floating-point arithmetic is never used for a posted financial amount.
• Every posted monetary amount carries, or belongs to a monetary artifact that carries, an ISO 4217 currency code. Amounts in different currencies are never added together merely because their numeric values look compatible.
• Cart, order, payment, refund, gift-card, store-credit, monetary-reward, and monetary-report rows in one commerce flow must agree on currency. A mismatch fails closed; the system must not silently relabel money.
• Loyalty points are whole non-monetary units, not minor currency units. They do not carry an ISO currency and must never be formatted, summed, or reported as money. A separately labelled points-value estimate can apply the configured redemption rate, but it is not cash or posted customer credit.
• Sellerlane does not currently convert historical orders using an order-time FX table. Stores operating in one currency need no FX conversion. A store that later enables multiple order currencies must report them separately until an immutable order-time exchange-rate snapshot is available.

Why historical FX exists

Historical FX is needed only when an amount recorded in one currency must be shown or aggregated in another. Without an event-time rate, converting a June sale with July’s rate makes the June report change every day and breaks audit reconciliation. A complete conversion snapshot records the source amount and currency, reporting amount and currency, rate direction, rate/provider, and the instant used.

Keep two uses separate:

• Commerce reporting FX displays each sale or reversal using the historical rate for that event’s day. A later reversal is a new dated event; it does not rewrite the original sale.
• Payment and payout FX uses the provider’s actual authorization/capture, refund, chargeback, and settlement transactions. The refund rate can differ from the capture rate, producing a real exchange gain or loss.

Neither conversion is necessary for a store that prices, charges, refunds, and reports exclusively in the same currency. Until both snapshots exist, Sellerlane keeps unlike currencies separate instead of applying today’s rate or pretending the numeric amounts are comparable.

Analytics dashboard targets

A money target is a comparison threshold, not a posted financial transaction. It is nevertheless stored with the same currency discipline as commerce money: an exact integer number of the configured ISO currency’s true minor unit. A JPY target has no fractional minor unit; a KWD target may have three. The seller UI rejects excess fractional precision instead of rounding it silently.

One target can bind to one canonical metric and one currency only. The target service rejects a different currency, and target hydration verifies that the canonical report returned the snapshotted currency before it computes attainment. It never adds USD and INR, applies today’s FX rate, or labels one currency as another. Counts, basis-point rates, and non-monetary decimals use separate columns and cannot carry a currency.

A target does not change sales recognition, payments, liabilities, inventory, tax, or any report fact. It reads the canonical metric for a fixed store-local period and compares that value to the threshold. Event-dated corrections still land on their own reporting date; a refund can therefore move the current value of a period whose fixed dates include that refund event without rewriting the target or the original sale.

Which date owns an event?

Commerce is event-dated in the store’s reporting timezone:

Event	Reporting date
Original sale and eligible order count	Order creation date
Payment	The payment’s processed date
Refund	The refund’s successful processed date
Return merchandise reversal	The linked refund/return processing date
Cancellation or order edit	The adjustment’s processed date
Store-credit issue, redemption, expiry, or reversal	The immutable ledger transaction date
Loyalty/referral/review award	The date the award actually vests or is reversed, not the date it was merely proposed

A refund in July for an order placed in June creates a negative July sales event. It does not rewrite June’s original sale. This keeps closed periods stable while the selected date range still reconciles when both events are included.

The exact-grain Net sales from gift cards report is a deliberate Shopify-shaped exception. It is sale-grain: Date and Sale ID remain the original gift-card sale, and a later cancellation/edit/refund updates that original row’s net items and net sales. The reversal is still accepted only when processed, but this one report can change when the original sale period is run again.

Sales definitions

The formulas below name reductions by their positive magnitude. Operational breakdowns may also show that positive magnitude. Structured sales report rows instead expose Discounts, Returns, and Sales reversals as negative signed contributions so a merchant can add the displayed components to reach the displayed total. The field description states which presentation is in use; never negate or subtract a signed reduction again.

Metric	Definition
Gross sales	Original merchandise unit price × ordered quantity, before discounts. Gift-card face-value issuance is excluded because it creates a liability rather than merchandise revenue.
Discounts	Merchandise discounts allocated to eligible lines at order time. Gift-card and store-credit redemption are tenders, not discounts.
Merchandise sales reversals / returns	Merchandise value removed by a processed refund, return, cancellation, or order edit. The detailed report distinguishes the event type.
Total sales reversals	Merchandise reversal plus any reversed shipping, tax, duties, tips, additional fees, and explicit adjustments. It is the negative contribution removed from total sales, not the same as merchandise returns alone.
Net sales	gross sales − discounts − merchandise sales reversals
Total sales	net sales + shipping + taxes + duties + tips + additional fees ± explicit order adjustments
Average order value	(order-time gross sales − order-time discounts) ÷ eligible non-gift-card orders

Duties participates only when an immutable duties amount is actually persisted. The current Sellerlane order source has no duties amount, so the public finance preset omits the field instead of presenting a fabricated zero.

Average order value deliberately excludes shipping, tax, duties, tips, fees, gift-card-only orders, and later refunds or edits. A later refund therefore does not change the historical AOV numerator or denominator of the original order day.

A sale is recorded when the order is placed. Pending, unpaid/voided, and later-canceled orders therefore enter the order-date sales facts; cancellation, edit, return, and refund effects appear as separate negative events on their processed dates. Test and deleted orders are excluded. Payment status belongs in payment/finance reporting and never decides whether the original merchandise sale existed.

Original sales, event-net sales, and customer value

These three views of the same commerce history must not be interchanged:

Basis	Meaning
Original / order-time sales	The eligible order components booked when the order is placed. A later event never rewrites this row. This is the basis for order-date sales, acquisition chronology, and canonical AOV. “Booked” here describes the operational order fact; it does not mean cash receipt or accounting revenue recognition.
Event-net sales	Original sales plus signed cancellations, edits, restorations, returns, and refunds on each event’s processed date. A selected day can be negative. Total-sales reports include total-sales components; product/cohort reports use their narrower documented merchandise basis.
Customer value snapshot	Signed event-net activity accumulated through one snapshot date for one identified customer. It is a point-in-time balance-like analytic measure, so daily snapshots must not be added together.

RFM monetary value and actual lifetime value use the same customer-value basis: lifetime event-net total sales through the snapshot, floored at zero per customer. They include original reportable total sales, signed cancellation/edit/restoration facts, successful non-gift-card refund allocations, and truthful order-level total-sales refund residuals. They do not subtract an undifferentiated gateway refund field, because that money can include gift-card value or another tender/component that was never ordinary sales. Sold gift-card face value and its allocated refund/reversal remain in gift-card liability reporting.

RFM recency and frequency use eligible order placement chronology, not payment or reversal dates. A later reversal changes monetary value but does not erase the historical order from frequency. Actual lifetime value is historical operational customer spend—not margin, future predicted value, cash received, or a general-ledger balance. The LTV report’s Average order value is computed independently from order-time gross merchandise less discounts divided by eligible orders. It is not actual LTV ÷ lifetime orders, because actual LTV also contains total-sales components and later event-dated reversals.

Guest sales without a stable customer identity remain financially real but cannot enter a customer snapshot. Gift-card-only, test, and deleted orders do not create customer purchase history. Customer monetary snapshots fail closed when an order or reversal currency cannot be reconciled to the configured store reporting currency; they never relabel or add unlike currencies.

Customer lifecycle sales reports use that same signed event-net total-sales ledger but do not apply the per-customer snapshot floor. Original sales retain the order placement date. Cancellation, edit, restoration, refund-line, and truthful order-level refund-residual amounts retain their processed dates and the original order’s first-time/returning classification. This means a later period may contain negative new-customer sales without any new customer count. Sold gift-card face value and its line refund are excluded as liability activity; mixed or unknown event currencies fail closed until historical conversion is available.

Customer counts never use reversal rows. They require a stable customer ID and exclude guest orders and POS walk-in holder records without removing those sales from ordinary store/POS financial totals. The one-time/returning detail lists snapshot accepted marketing at order placement and read that immutable value from the customer’s most recent eligible order; today’s mutable consent is not an acceptable financial or audit substitute. The checkout answer is persisted before hosted-payment redirect so an asynchronous provider webhook cannot create the order without it. If no explicit choice exists, the canonical subscribed state at placement time is recorded with its evidence source.

The stored value is evidence for the historical customer report, not authority to send a campaign later. Delivery always checks current canonical subscription and suppression state. If the order has an email address, only that normalized address can supply the placement-time subscribed state; another email linked to the customer cannot transfer its consent to the order address.

Customer-profile spend and segmentation deliberately use a fourth, separately named basis. Amount spent sums max(order total − raw payment refunds, 0) across paid-ish, uncanceled, non-test orders. It includes tax and shipping and can include money used to purchase a gift card, because it answers “how much did this customer pay?” rather than “how much sales revenue did the store recognize?” Average spend per paid order divides that customer-profile amount by the matching order count. The segment query key remains average_order_value, but the merchant-facing label and documentation do not call this analytics AOV. It must not be mixed with order-time merchandise AOV, RFM monetary value, actual LTV, or payment cash flow.

The same sales formula applies online and at POS. A gift-card-only POS checkout belongs to gift-card liability/payment reporting and contributes neither an ordinary POS order nor merchandise sales or AOV. In a mixed checkout, only the non-gift-card merchandise is ordinary sales; gift-card/store-credit redemption is tender and does not reduce gross or net sales.

Marketing reports label the model-credited version Attributed AOV. It is attributed order-time gross merchandise sales less discounts ÷ attributed orders. It excludes shipping, tax, duties, tips, fees, and later reversals. Attributed total sales per order is a separate shipping/tax-inclusive ratio and must not be presented under the AOV label.

Revenue is not a universal financial basis. On the commerce Overview it means event-net total sales under the formula above. Structured report fields use a stable revenue key for compatibility but expose a basis-specific label and definition:

• traffic, device, landing-page, search, checkout, and session-conversion attribution report order-time total sales, so later reversals do not rewrite the acquisition cohort;
• marketing attribution reports model-credited order-time total sales and then apply credited cancellation, edit, and refund reductions on each reversal’s processed date while retaining the original touchpoint and attribution model;
• product, variant, collection, and vendor reports use event-dated net merchandise sales and exclude shipping, tax, duties, tips, fees, and unallocatable order-level refund residuals;
• The Shopify-shaped recommendation conversion preset is a nested session funnel and has no revenue field. Sellerlane’s additional placement/product diagnostic reports original-order attributed net merchandise sales selected from the most recent same-session click before order creation; later reversals are intentionally outside that diagnostic and never masquerade as Shopify’s funnel;
• cohort First order uses acquisition-order net merchandise sales while showing a 100% acquisition baseline; repeat periods include repeat-order sales plus signed line reversals or restorations on their processed date and can be negative; reversals do not count a customer as returned, and gift-card-only checkouts are excluded from customer chronology; and
• COD revenue is the original order value, not the deposit, collected cash, or outstanding balance.

None of these meanings is gateway settlement, cash received, taxable income, or recognized accounting revenue. The metric catalog description is authoritative for metric-first exploration; reports must never collapse the labels back to an unqualified “Revenue.”

Operational breakdown columns show refund and cancellation amounts as positive magnitudes; signed sales result columns show their contribution as negative. Payment Refunds is also a positive cash-flow magnitude and Net payments subtracts it once. Do not combine or subtract both presentations. The order-grain Total sales reversals by order report includes line-attributed cancellation, edit, and refund reversals plus the order-level residual for full, itemless, or custom refunds. A residual with no truthful product allocation is emitted as an order-grain, null-product row: it completes the order’s total-sales reversal without inventing merchandise, COGS, or gross-profit attribution for a product that was not identified.

The signed Total sales by order source applies the same conservation rule to the complete signed order ledger: the original order enters once at creation, refund lines enter once at successful processing, and only the portion not represented by those lines enters as the order-level residual. Known shipping, shipping-tax, fee, and adjustment refunds keep their component; an amount-only custom item refund can reduce order-grain Net sales without being assigned to a made-up product. The same source powers Weekly sales patterns, where signed Net sales is grouped by store-local weekday and hour of the sale/reversal event. The totals execute, but full Shopify finance-row parity is still partial until product-title-at-sale rows, separate shipping sale rows, duties, and return fees have authoritative source fields and captured-export reconciliation.

Sales are not payments

An order can be created, paid, fulfilled, returned, and refunded at different times. Keep these concepts separate:

• Amount due is the order’s external/manual tender base after subtracting gift-card and store-credit applications: total − gift card applied − store credit applied. It is immutable with respect to later external captures and must not be displayed as the remaining collectible balance.
• Amount paid is successfully captured external or manual payment. Gift card and store credit are kept in their own application/ledger fields and are not folded into this column.
• Remaining external amount to collect is max(amount due − amount paid, 0).
• Total tendered is amount paid + gift card applied + store credit applied.
• Refunded amount is a successfully processed financial payout. It can include merchandise, tax, shipping, or other components, so it is not interchangeable with merchandise returns.
• Gateway settlement is what a provider transfers after provider fees, reversals, reserves, and timing differences. It must be reconciled to payment transactions, not to gross sales.

Pending, failed, canceled, and test-mode transactions do not become settled money. They may appear in an explicitly named attempt/operations view, but never in Gross payments, Refunds, or Net payments. Idempotency keys ensure a provider retry cannot post the same payment or refund twice.

Payment-flow report definitions

Payment reports use successful, money-moving transaction events. They are dated by processed_at in the store reporting timezone and grouped by the payment method, gateway provider, and gateway mode snapshotted on that transaction. The canonical measures are:

Metric	Definition
Transactions	Number of successful capture/payment rows plus successful refund rows. An authorization, failed attempt, cancellation, void, or other non-settling row is not a transaction in this report.
Gross payments	Sum of successful capture/payment amounts, before refunds.
Refunds	Absolute amount of successful refund transactions, shown as a positive operational flow.
Net payments	gross payments − refunds. A period may be negative when refunds for older captures exceed captures processed in the period.

Authorization diagnostics are a different population. Attempts counts distinct intent/auth/capture attempt identities; a refund row does not become a new attempt, and an authorization plus its later capture is not counted twice when both share the same attempt ID—even across reporting days. The attempt is assigned to its first qualifying lifecycle-event day. Failed and canceled attempts can appear in that diagnostic population without contributing settled money.

The exact Payments by order source additionally presents all successful tender flows at event grain, including manual/cash/COD captures, gift-card redemptions, and store-credit redemptions. In that signed ledger, tender inflows are positive and refund/outflow rows are negative, so Net payment is a direct sum. The operational daily payment report instead displays Refunds as a positive magnitude and calculates Net payments = Gross payments − Refunds. These are two presentations of the same direction and must not be combined or subtracted twice. Gateway/manual events use transaction processed_at; gift-card and store-credit events use their immutable ledger posting time.

The source ledgers do not all store direction the same way. Normalize by the typed event before combining them:

Source	Stored sign contract
Gateway/manual payment transaction	amount_cents is a positive magnitude for both captures and refunds; kind supplies the direction. A report presents a refund either as a positive Refunds magnitude or a negative signed outflow, never both.
Gift-card transaction	issued and refunded are positive credits; redeemed and expired are negative debits; adjusted can have either non-zero sign.
Store-credit account ledger	Positive rows credit the customer liability and negative rows reduce it. refund and promotion are positive; order_payment is negative; reward clawbacks and administrative adjustments are typed adjustments, not redemptions.

Raw amount_cents values from these ledgers are therefore not directly additive. The report adapter owns the one direction normalization; callers must not infer a second sign from a label or negate an already signed row again.

These measures are not gross sales, net sales, total sales, amount due, or a gateway payout. They do not infer payment flow from the order’s current financial status. A successful refund can reverse sales components and create a payment outflow, but those are two views of one event in two different ledgers: the sales report applies the signed component reversal and the payment report subtracts the positive refund amount exactly once. Never combine them into one formula by subtracting both.

Provider taxonomy is an external reconciliation boundary. Sellerlane reports the immutable method/provider snapshots stored on its own transaction; it does not guess a Shopify Payments, Shop Pay, manual-tender, settlement, fee, chargeback, or payout classification from a display label. The payment presets therefore remain executable but unreconciled until the same controlled transactions produce both a captured production Sellerlane report and a captured Shopify export for comparison.

Operational contribution estimate

The Overview does not claim accounting net profit. Its Operational contribution estimate is:

event-dated merchandise gross profit + signed shipping + signed tips + signed additional/return fees + signed order adjustments − outbound shipping cost − payment fees

It excludes customer sales tax, duties, overhead, payroll, marketing spend, financing, income taxes, reserves, chargebacks, and any cost not explicitly listed. Merchandise and customer-facing component reversals use their processed event dates; the snapshotted outbound shipping cost stays on the original order date. Treat this as a commerce contribution diagnostic, never GAAP/IFRS net income.

Refunds, returns, cancellations, and chargebacks

• A return records the physical/logistics lifecycle of goods. A refund records financial value returned to the buyer. Either can exist without the other.
• Only a successfully processed refund changes refunded money and financial reports. A requested or failed refund does not.
• Merchandise, tax, shipping, duties, fees, and tender restoration are allocated explicitly. The sum of allocations must equal the posted refund amount.
• Canceled unfulfilled quantities release inventory and reverse their sales components on the cancellation event date. Restocking fulfilled goods occurs only through the selected refund disposition or a return receiving.
• Restoring a previously canceled or removed quantity is a new positive signed sales adjustment on the restoration’s processed date; it does not delete the earlier reversal.
• A chargeback or fraud reversal is its own event and must not be disguised as a product return.

Chargeback-rate denominator

Chargeback count and amount use the provider dispute’s opened date. Winning a dispute does not erase that it was opened. The rate denominator is successful, live, gateway capture/payment transactions processed in the selected period; it is never orders placed or orders risk-assessed.

chargeback rate = disputes opened in the range ÷ eligible payments processed in the range

The two event populations share a reporting period but do not imply that each dispute belongs to a payment made in that same period. A single day can therefore exceed 100% when old payments are disputed during a quiet payment day. Month and rolling-window totals divide the summed numerator by the summed denominator; they never add daily percentages. Fraudulent chargeback rate uses the same denominator and only the provider reasons explicitly normalized as fraudulent. Sellerlane currently combines its supported live gateways, so the result remains a gateway-scope reconciliation item against Shopify Payments.

See Refunds and returns for the workflow.

Discounts and allocation

Discount eligibility is resolved against a cart snapshot. Once an order is created, the order stores the chosen applications and per-line allocations. Those allocations—not a later re-evaluation of current promotion settings—drive refund caps and reporting.

When an indivisible minor unit must be split, Sellerlane uses deterministic largest-remainder allocation:

1. calculate each line’s exact proportional share;
2. floor every share to a whole minor unit;
3. distribute the remaining minor units by largest remainder with a stable tie-breaker.

The allocated children must always sum exactly to the parent amount. No cent or paise may be created or lost.

Bundles and upsells

A bundle has a commercial parent and fulfillment/inventory components. The parent price is allocated to components so tax, discounts, refunds, COGS, inventory, and fulfillment remain auditable.

• A fixed price is one price for the selected offer group.
• Percentage off and amount off reduce the selected group’s eligible component subtotal. An amount-off value is not repeated once per component unless the offer explicitly says so.
• Returns are processed only at component-line grain. Each selected component’s refund is capped by its snapshotted allocation, and its return quantity and restock lifecycle are recorded independently. There is currently no whole-bundle return policy; returning every item means selecting every component quantity under the same component-return contract.
• Bundle availability derived from components uses the limiting component. Nested bundles are not supported.

An accepted cross-sell or upsell becomes an ordinary snapshotted cart/order line (or line group). Its merchandise, tax, inventory, fulfillment, return, and refund follow the same rules as the equivalent directly added item. The source rule and placement are offer-attribution provenance, not a second sale or a separate kind of revenue; any offer price reduction is retained as its allocated discount. Checkout- or payment-amending post-purchase upsells are not part of this contract.

Bundle analytics allocation boundary

Bundle analytics reads the same immutable child allocations used by checkout, tax, refund, and inventory rather than re-evaluating the current bundle. Every event retains two identities: the stable fixed-bundle product/variant or bundle- rule source ID, and the order-time title/handle/configuration snapshot. Component product/variant IDs and sale-time title/SKU snapshots are retained separately. This makes a later rename or bundle edit visible without silently rewriting history.

The signed report stream is:

attributable bundle/component sales = signed net component merchandise + signed item tax

Original merchandise and item tax enter on the order day. A successful component refund enters −(refunded merchandise + refunded item tax) on the refund processed day. A cancellation or order edit enters the inverse of its retained component merchandise and item-tax reversal on the adjustment processed day; a restoration therefore has the opposite positive sign. Refunds and edits join back to the original order-line-child, so they cannot lose or change the bundle classification.

Shipping, shipping tax, duties, tips, order-only fees, and residual order adjustments are outside this component metric. One order can contain several components but only one such order-level amount; no retained fact says which component owns it. Sellerlane therefore does not divide it by price, quantity, or component count. The general order-grain Total sales formula still includes those components, while bundle/product-grain reports expose the narrower, honestly named attributable amount.

Likewise, Net bundle component items is the sum of signed component quantities. It is not a count of parent bundles. A partial component refund does not contain enough evidence to say that a whole bundle was reversed; rounding, taking a minimum, or proportionally converting it would fabricate a result. The Shopify-shaped bundle presets remain PARTIAL_SALES_COMPONENTS and never claim captured parity until controlled Shopify exports settle those allocation and partial-reversal rules.

See Bundles and upsells.

Store credit

Store credit is an account-bound monetary liability represented by immutable lots and transactions.

lot remaining = issued − consumed − expired − reversed

spendable available = Σ max(unexpired lot remaining − its active reservations, 0)

authorized reserved liability = Σ active reservation allocations

outstanding liability = spendable available + authorized reserved liability

The reserved-liability term includes a still-live authorization created before its lot expired. It is reported separately from spendable balance and remains currency-scoped; a currency-blind customer counter is never used as a financial total.

Reservations make value temporarily unavailable but do not spend it. Successful order completion consumes the reserved allocations exactly once; cart expiry or checkout failure releases them. A reservation created while a lot is valid authorizes only its allocated cents through that reservation’s short TTL. It does not protect any unreserved remainder or renew the lot. If the reservation is released after the lot’s expiry date, those cents become due for expiry on the next sweep; if it is consumed first, checkout settles the prior authorization exactly once.

Consumption uses first-expiring, first-out ordering, followed by non-expiring lots. At the end of an expiry date in the store timezone, the sweep expires the lot’s unreserved remaining amount. A later release makes its formerly reserved amount eligible for the next sweep. Expiry posts an immutable transaction and updates available balance, outstanding liability, lifetime expired value, and the next-expiry date together.

Store credit is a tender, not revenue and not a discount. Issuing it increases a liability; redeeming it reduces the liability and the order’s amount due without reducing gross or net sales. The daily issued volume is the sum of positive ledger credits, including refunds, promotions, and vested reward credits. The daily redeemed volume includes only negative order_payment rows. A reward clawback or administrative debit reduces outstanding liability but is not customer redemption and must not be relabeled as one. See Store credit.

Gift cards

A gift card is bearer value identified by a secret code; store credit belongs to a customer account. Gift-card issuance increases an outstanding liability and redemption decreases it. Redemption is a tender and therefore does not reduce sales.

Gift-card commerce has three deliberately separate views:

• Gift-card gross sales is the face value issued by sold gift-card product lines.
• Gift-card discounts is the difference between that face value and the price charged for the sold card.
• Net sales from gift cards is sold face value minus its discount and linked gift-card-line reversals/refunds. It is a sale-grain report: Date and Sale ID remain the original sold-card line even when a later processed event reduces its net items or net sales. It is excluded from ordinary merchandise sales and AOV.

Creating a card administratively has no sale and no customer payment. Selling a card creates liability and the tender used to buy it creates a payment flow. Redeeming the card later reduces liability and pays for the new order without reducing that order’s full sales value. Refunding value back to a gift card is a gift-card payment entry and restores liability; it is not a second merchandise discount. A checkout reservation created while the card was valid remains a short-lived authorization; the expired timestamp blocks every new reservation, but the existing one must be consumed or released rather than orphaned. Once the expiry instant passes, new spend is blocked immediately; the financial expiry is then realized transactionally by the customer-service access path or the scheduled 30-minute sweep. That realization posts the unreserved value as a negative immutable liability transaction and reduces card balance to the reserved amount. Its reporting time is the actual ledger posting time, not a fabricated backdate to the contractual expiry instant. Consumption then posts the ordinary redemption debit; release makes the reserved value eligible for a final expiry debit. A zero-balance card can change to expired without fabricating a zero-value money movement. The scheduled sweep applies the same reservation-aware rule to untouched cards and to disabled cards. Disabling a card changes spendability, not the merchant’s obligation, so its remaining balance stays in outstanding liability until redemption, refund adjustment, or expiry posts a signed movement. Ledger redemption rows are negative debits; the dashboard’s “gift cards redeemed” value is their positive absolute volume.

Sellerlane’s current launch contract is currency-exact: a card and an order must use the same currency. Cross-currency gift-card redemption requires an immutable conversion snapshot and is not silently approximated. See Gift cards.

Loyalty, referral, and review rewards

Reward families have related but not identical lifecycles. Conceptually, value moves from proposed/pending/held to vested or issued, then to reserved/used only when that instrument supports reservation, with terminal expired, revoked, or clawed back transitions where applicable. A referral discount, a loyalty point lot, and a store-credit lot do not traverse one shared status graph.

Their financial meanings are also different:

Instrument	Financial meaning
Loyalty points	Whole promotional units in the append-only points ledger. Pending, available, reserved, expired, redeemed, and unrecovered points are not ISO-currency money or store-credit liability.
Discount code	A promotional instrument. Issuance alone is not sales reduction or customer-credit liability; a valid application reduces the eligible order price.
Reward store credit	Monetary customer liability begins only when the linked store-credit lot and ledger credit are issued. A pending proposal or approved eligibility record is not that liability.

The current typed loyalty contract is deliberately narrower than the underlying artifact tables: earning rules mint points only, and published catalog redemptions accept amount discounts, percentage discounts, and free shipping. Free-product, gift-card, and store-credit loyalty redemption rules fail validation and must not be exposed as active customer promises. Referral and review systems can independently issue their documented discount or store-credit rewards; that does not make those instruments supported loyalty redemption kinds. A points-type review reward’s internally named amount_cents value is a point count, not money, and must be interpreted only after checking its reward type.

• A pending award is not spendable and is not an outstanding customer balance.
• Vesting is idempotent: the same qualifying order, review, or referral cannot issue the same award twice.
• A cancellation, refund, chargeback, rejected referral, or removed qualifying artifact can reverse an award according to its snapshotted rule. A reversal never deletes the original ledger entry.
• Store credit created by a reward becomes an ordinary store-credit lot; the reward record links to it instead of maintaining a second spendable balance.
• Review rewards are rating-neutral. Qualification may depend on verified purchase and content type, but never on positive sentiment or a minimum star rating above the universal minimum.
• A photo/video review reward uses the review’s clean, publication-ready, merchant-visible media flags. An upload intent, attached Pending object, scanner-approved object that has not completed private-to-public promotion, rejected object, or scan failure is not qualifying performance and cannot vest or issue a media reward. The flag changes only after a trusted scanner records Clean and the durable promotion worker records Public ready; removal or hiding then recomputes the flag and follows the normal audited reward-reversal policy.
• The attachment window closes explicitly from a signed, store-and-review-bound capability (or at its fixed expiry for an abandoned browser flow). Reward evaluation waits until every visible attachment is terminal, freezes a monotonically versioned qualification generation, and CAS-stamps only that generation. A stale worker cannot pay or mark a newer generation evaluated.
• Reward-rule eligibility is decided at that immutable qualification time, not at upload intent or initial text submission. The winning review type and full discount/store-credit rule definition are copied into the reward snapshot; amount, currency, scope, and expiry never reread a later merchant-edited or deleted rule. Until qualification is frozen, customer copy says only that any eligible reward will be determined after approval—it does not promise the richest advertised tier. A reissue archives the complete prior rule snapshot, artifact IDs, amount/currency, dates, status, and all clawbacks as a prior generation before clearing any current fields; clawbacks append to history instead of replacing earlier recovery evidence.
• Hiding or deleting media revokes a photo/video reward only when the aggregate flag for its snapshotted winning tier becomes false. Another clean, ready photo or video keeps the matching tier qualified. The review_reward_rules engine selects and pays exactly one richest matching payout per review; its tiers do not stack with one another. A separately configured loyalty review earn can contain two intentionally stacked ledger lots—base review points plus an optional media bonus. Those loyalty components can coexist with a discount or store-credit review incentive. When the selected review incentive itself is points, the loyalty rule owns the points award and suppresses the duplicate review-incentive points mint. Loss of the last qualifying media reverses the loyalty bonus, not its base earn.
• A delayed media reminder opens a distinct seven-day content-only window only after the reward generation is evaluated. Every object attached in that window carries an immutable non-reward-qualifying flag. Its scan, publication, hide, unhide, or deletion may change storefront presentation but cannot reopen the candidate, increment the frozen qualification generation, upgrade a tier, restore a bonus, or alter an issued/used amount. The database rejects any attempt to promote that flag from false to true and any direct reward-eligible insert after qualification. Qualification time, frozen photo/video facts, and generation version are write-once once frozen. A delivery retry reuses the first persisted seven-day deadline; it cannot extend the offer, and an expired reminder is not restaged with a dead link.

Referral-risk failure boundary

Referral risk is an authorization gate for the advocate reward, not a second payment decision for the referred customer’s order. The qualifying paid order and its sales/payment facts remain committed even if risk processing fails. The system first captures a privacy-minimized evidence snapshot at qualification, then evaluates only that persisted snapshot. An evaluation failure leaves the advocate award pending and non-spendable and a durable worker retries the same bytes and fingerprint—not current customer, order, address, or event rows.

If source capture itself fails, there is no defensible historical snapshot to retry. The award remains fail-closed in evaluation_capture_failed for operational repair/replay; it is never released by querying mutable data later.

A successful evaluation records either an immutable no-signal completion or a merchant-review case. The issuer consumes that recorded result; it does not run the risk query again with a later clock. A merchant decision binds to the exact evidence fingerprint reviewed and requires a reason and operator. Once source capture completes, later customer/order/event activity cannot modify or reopen that evidence. Until approval and normal vesting conditions both succeed, the proposed reward is neither issued customer value nor an outstanding store-credit liability.

Referral award/case state	Financial meaning
Pending eligibility	A proposed future benefit. It is not spendable and is not store-credit liability.
Evaluation pending	A fail-closed technical authorization hold backed by a durable retry of the stored immutable snapshot. It is not a fraud verdict and cannot be merchant-approved.
Evaluation capture failed	The source snapshot was not durably captured. The proposed award remains non-spendable and requires operational repair; neither a worker nor merchant may reconstruct/approve around it.
Pending merchant review	Uncertain first-party evidence exists. The proposed award remains non-spendable.
Approved	The fraud authorization gate passed for the reviewed evidence fingerprint. Fulfillment, return hold, cap, currency, and order validity still control issuance.
Issued store credit	One linked store-credit lot and ledger entry now exist; outstanding liability starts here, not when the referral qualified or was approved.
Issued discount code	A promotional instrument exists. The discount affects sales only when it is validly applied to an order; unused code face value is not store-credit liability.
Rejected/canceled	No new value may issue. Reversible unused issued value is voided with compensating history.

The disposable-email result is fixed at attribution. Address/order inputs and signup-event device/network populations are bounded at qualification; the 24-hour velocity window is [qualification − 24 hours, qualification]. The resulting normalized evidence JSON and fingerprint are immutable database fields. A completed no-signal result is recorded just as durably as a case result, preventing a worker or issuer from changing the answer after later email edits, address edits, event inserts, or clock movement.

Merchant actions are optimistic-concurrency operations: the request supplies the exact normalized evidence fingerprint reviewed. A stale or mismatched fingerprint fails closed. The action, reason, operator, fingerprint, and idempotency key form the immutable audit record; the same key can replay only that same tuple.

Pending evidence has no financial side effect on value already issued; it may create a review flag but cannot disqualify the referral or claw back value. Approval preserves that economic state. Rejection is the sole fraud-review decision authorized to cancel or claw back. Rejection after issuance can reverse only value that is still reversible. An unused advocate discount can be disabled; unspent store-credit lot value can be voided. A discount already used or credit already consumed remains historical commerce and is never erased or made negative by inference. Further recovery requires an explicit, separately authorized adjustment.

“Suspicious referral” and fraud-review queue counts measure triage cases, not confirmed fraud, loss, chargebacks, or recovered money. Reports must keep those counts separate from pending reward amount, issued value, reversed value, and outstanding store-credit liability.

See Loyalty and referrals and Review requests and rewards.

Inventory, cost, and profit

• Saleable inventory changes through an append-only movement/ledger event and a materialized current balance. Replaying the same business event is idempotent.
• COGS uses the cost snapshot attached to the sold component at the relevant sale event. A processed return reverses only the cost of the returned quantity.
• Gross profit is net merchandise sales less COGS for rows with cost data. Shipping, tax, tips, and payment fees are not merchandise margin.
• Profit reports expose cost coverage. Missing cost is not silently treated as a confidently known zero-margin or full-margin sale.

Reconciliation invariants

The following must hold for every store, currency, and reporting period:

• order component allocations sum to the order total;
• external/manual amount paid plus remaining external amount to collect equals amount due, and amount due plus gift-card/store-credit applications reconciles to the current order total;
• successful refunds never exceed captured/refundable value;
• bundle child allocations sum to the bundle parent amount;
• bundle analytics merchandise plus item-tax events reconcile to their retained child allocations and never absorb an unowned order-level amount;
• store-credit and gift-card lots reconcile to their transaction ledgers;
• reservations plus available value never exceed unexpired remaining value;
• a failed referral-risk evaluation cannot roll back a paid order or make its pending advocate award spendable;
• review media cannot qualify a reward before a clean scan decision, committed canonical promotion, edge marker, public-ready record, and frozen attachment generation;
• each idempotency key produces at most one financial effect;
• rollups can be rebuilt from facts and produce the same result;
• no report adds different currencies together.

For report-specific definitions and traffic identity, see Analytics definitions.

Related guides

Analytics definitions

Sessions, visitors, sales metrics, dates, currencies, attribution, POS, and location semantics in Analytics definitions.

Refunds and returns

Apply the settlement and inventory rules through Refunds and returns.

Discounts

Configure eligibility and combinations in Discounts.

Store credit

Issue and redeem account-bound value in Store credit.