StockChange

Get a stockchange by ID

Retrieves a single stockchange by its unique identifier.

get/v1/stock-change/{id}

Request

  • Base URL: https://api.finalpos.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.finalpos.com/v1/stock-change/{id}
  • Auth: API key in header x-api-key

Path parameters

idstring required

StockChange ID

Response

The stockchange has been successfully retrieved.

idstring

Unique identifier for the StockChange.

createdAtstring date-time

Timestamp when the StockChange was created.

updatedAtstring date-time

Timestamp when the StockChange was last updated.

companyIdstring

Company ID associated with the StockChange.

userIdstring

User ID who made the stock change.

sourcestring

Source of the Stock Change Event.

productIdstring

Product ID affected by the stock change.

variantIdstring

Variant ID affected by the stock change.

variantNamestring

How variantId read on the day — attribute values or SKU, frozen at write. A rename or a deletion must not rewrite the ledger; the id above stays so the variant is findable historically. Absent on rows written before names were frozen — resolve those by id.

outletIdstring

Outlet ID where the stock change occurred.

baseAction'ADD' | 'REMOVE' | 'RECOUNT' | 'SKIP'

Base action type for the stock change.

specificAction'STOCK_RECEIVED' | 'INVENTORY_RECOUNT' | 'DAMAGE' | 'THEFT' | 'LOSS' | 'RESTOCK_RETURN' | 'REFUND_RESTOCK_RETURN' | 'REFUND_DAMAGE' | 'SALE' | 'COMPOSED_FOR_SALE' | 'UNIT_FAMILY_CHANGED' | 'TRANSFER' | 'BULK_RECOUNT' | 'APPLIED_FROM_WOO' | 'PO_RECEIVED' | 'EXTERNAL_SALE' | 'EXTERNAL_RESTOCK' | 'CUSTOM'

Specific action type for the stock change.

customActionIdstring

The company action used when specificAction is CUSTOM.

customActionNamestring

How the custom action was named on the day — renaming it later does not rewrite history.

quantitynumber

How much the shelf moved, in WHOLE BASE UNITS of the family — grams, millilitres, pieces. Not in unitId: that names the unit the movement was keyed in, and the two differ by the unit's ratio. unitQuantity is the same movement as the person keyed it.

updatedQuantitynumber

On-hand level after the change, in the SAME base units as quantity — again not in unitId. It has no keyed counterpart: a reader renders it by dividing with the ratio, so unlike unitQuantity this figure does restate if the unit is later re-rated.

unitIdstring

Unit this movement was keyed in — the one the person saw on screen. Differs from what moved when a variant draws from a sibling pool: three burgers leave a kilogram pool. Absent on entries written before units existed, which are pieces.

unitQuantitynumber

The amount as keyed, in unitId — frozen, never recomputed. quantity stays in base units for arithmetic; this is what the movement meant to the person who made it. Dividing the base amount by the unit ratio at read time would rewrite history: receive 5 burgers today, double the burger's weight tomorrow, and yesterday's entry would claim 2.5.

viaVariantIdstring

The variant the movement was keyed through when it is not variantId — the Glass that was sold when a Bottle pool drains. The row lands on the pool owner, whose balance moved; without this the ledger never names what was actually sold. Absent on direct movements.

viaVariantNamestring

How viaVariantId read on the day — same freeze as variantName.

compositeProductIdstring

The composite this item was sold (or refunded) in — "Sold in Combo #1" (FT-83, D26). Absent on every other movement.

compositeNamestring

How that composite read on the day — same freeze as variantName.

idempotencyKeystring

Caller-supplied key that lets the writer safely retry a stock mutation. The unique index drops duplicates so the same logical change is not applied twice. Keys prefixed sarnia: are RESERVED for the FinalPOS sync lane — its outbound subscriber skips those events as its own writes, so external callers must not use that prefix or their movements will not sync to connected platforms.

Example response

{
  "id": "o1p2q3r4s5t6u7v8w9x0y1z2",
  "createdAt": "2025-12-07T19:31:48.436+00:00",
  "updatedAt": "2025-12-07T19:35:48.436+00:00",
  "companyId": "o1p2q3r4s5t6u7v8w9x0y1z2",
  "userId": "507f1f77bcf86cd799439011",
  "source": "public-api",
  "productId": "507f1f77bcf86cd799439012",
  "variantId": "507f1f77bcf86cd799439013",
  "variantName": "Bottle",
  "outletId": "507f1f77bcf86cd799439014",
  "baseAction": "ADD",
  "specificAction": "INVENTORY_RECOUNT",
  "customActionId": "507f1f77bcf86cd799439016",
  "customActionName": "Exhibition loan",
  "quantity": 400000,
  "updatedQuantity": 359000,
  "unitId": "GRM",
  "unitQuantity": -3,
  "viaVariantId": "507f1f77bcf86cd799439015",
  "viaVariantName": "Glass",
  "compositeProductId": "507f1f77bcf86cd799439016",
  "compositeName": "Combo #1",
  "idempotencyKey": "sarnia:shopify:b54c8f9e-4c6a-4f5a-9d2e-7a1b3c9d0e2f"
}

Changes

No recorded changes to this operation across all 1 revision of this API.