Data Semantics

Business meaning that must be understood before aggregating API values. These rules are part of the API contract, not presentation-only labels.

Sales and returns

Sales transaction types are 51/52; return transaction types are 53/54.
quantity is the raw line quantity. Use netQuantity for signed merchandise aggregation; returns are negative.
grossSalesAmount, netSalesAmount and cogsAmount are signed so returns reduce totals.
discountPercent/discountAmount describe the item/line markdown or discount. invoiceDiscountAmount is the invoice-level discount allocation stored on the line.
isItemDiscounted and isInvoiceDiscounted identify those two discount mechanisms; isDiscounted is true when either applies.
salespersonId/salespersonName are line-level sales-associate references.
customerId and loyaltyCustomerId are separate identity namespaces. They may both be null, either may be present, or both may be present. The API does not expose customer phone/email/name as part of this sales linkage.

Purchases and landed cost

Transaction type 1 is Purchase; type 2 is Purchase Return. Signed cost/quantity fields reverse on returns.
lineForeignAmount is the raw line amount. foreignCostAmount, localCostAmount and landedCostAmount are signed business values.
landedExpenseAmount = landedCostAmount - localCostAmount.
Discount Earned is document-level. documentDiscountEarned is not allocated to purchase item rows and does not reduce line acquisition/landed cost.
Document-level totals repeat on each row of the same purchase. Do not sum those header fields across lines; group by the purchase document first.

Inventory and movements

inventory is a current balance/valuation contract. For dated flow analysis use inventory/movements.

movementType	Meaning	Typical sign
`PURCHASE`	Received purchase stock.	Positive
`PURCHASE_RETURN`	Stock returned to supplier.	Negative
`SALE`	Merchandise sold.	Negative
`SALE_RETURN`	Customer return into stock.	Positive
`TRANSFER_OUT`	Stock leaves the source store.	Negative
`TRANSFER_IN`	Stock arrives at destination store.	Positive
`STOCK_ADJUSTMENT`	Signed inventory correction.	Positive or negative
`STOCK_DEPRECIATION`	Write-off/depreciation movement.	Negative

Transfers

A transfer exposes both sides: sourceMovementQty is negative and destinationMovementQty is positive. For a balanced transfer those movements cancel when aggregated across both stores.

Markdowns, promotions and coupons

markdownPercent is expressed in percentage points: 25 means 25%.
promotionType controls the meaning of getValue. It is not one universal unit. Examples include quantity for Buy/Get, bundle price for Bundle and a discount rate/value for discount-oriented promotion types.
Promotion relationship endpoints expose the stores/items/client categories/tiers/cashback stores attached to the promotion.
Discount-coupon endpoints expose event metadata and store eligibility. Raw coupon codes/prefixes are intentionally not exposed.