Record a stock movement on a (sku, location) line

POST

/stock/movements

curl --request POST \
  --url https://quikstik-core.fly.dev/stock/movements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --header 'x-tenant-id: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --data '{ "sku": "example", "location": "example", "magnitude": 1, "reason": { "reason": "received" }, "down": false }'

• Production

Appends one movement (receive / sell / consume / promote-to-resource / transfer-out / adjust) to the append-only stock ledger for a tenant-defined sku at a location. The server loads the line’s fold, runs the gate (non-negative on-hand, currency, and amount checks — violations return 422), and persists the movement idempotently. magnitude is positive; the reason resolves the sign. For a downward adjustment (shrinkage/damage) set down: true with an adjusted reason. Units are dimensionless counts whose meaning the tenant owns.

Authorizations

• bearerAuth

Parameters

Header Parameters

x-tenant-id

required

string format: uuid

Tenant identifier (UUID).

Authn/authz semantics are intentionally TBD for this contract slice; this header exists to keep the contract explicitly multi-tenant from day 0.

Idempotency-Key

required

string

>= 1 characters

Idempotency key for the command envelope. A retry with the same key is a no-op.

Request Body^required

Media typeapplication/json

object

sku

required

Tenant-defined SKU — opaque to core.

string

>= 1 characters

location

required

Tenant-defined location — opaque to core.

string

magnitude

required

Positive count; the reason (and down) resolve the sign.

integer format: int64

>= 1

reason

required

A tagged stock reason. The reason discriminator selects the variant (received, sold, consumed, promoted_to_resource, transferred_out, adjusted); remaining fields are the variant’s payload (e.g. received carries unit_cost_minor + currency). The server-side domain type is authoritative for payload shape.

object

reason

required

string

Allowed values: received sold consumed promoted_to_resource transferred_out adjusted

down

For adjusted only — when true the adjustment decreases on-hand.

boolean

Responses

202

Movement recorded; the assigned stream sequence is returned

Media typeapplication/json

object

seq

required

The append-only sequence assigned to this movement in the line’s stream.

integer format: int64

Example ^generated

{
  "seq": 1
}

400

Malformed body

Media typeapplication/json

object

reason

required

string

Example ^generated

{
  "reason": "example"
}

401

Missing or invalid session bearer token

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

403

The session’s effect authority does not cover this operation

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

422

The command is rejected by a domain lifecycle gate (illegal state transition)

Media typeapplication/json

object

code

required

Stable machine-readable error code

string

message

required

Human-readable explanation (never leaks SQL, URLs, or secrets)

string

Example ^generated

{
  "code": "example",
  "message": "example"
}

503

No durable backend is wired for this operation (fail-closed)

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}