Record a cash movement (mouvement de caisse) on a session

Records one signed cash movement (mouvement de caisse) on an open drawer — a positive amountCents is a pay-in, a negative one a pay-out; zero is rejected. The session is addressed by the PATH id, which is authoritative: a sessionId in the body is ignored, never honoured. Returns the updated session. Supply an optional idempotencyKey so a retried or offline-replayed request resolves to the already-recorded movement instead of double-recording (409s only if the same key is reused for a different amount/reason). 404s for an unknown session; 422s when the movement is illegal — a pay-out that would overdraw the drawer, or any movement on an already-closed session.

POST /v1/sessions/{sessionId}/movements

Error

A valid request URL is required to generate request examples

200

{
  "id": "sess-ok",
  "storeId": "store-1",
  "registerId": "reg-1",
  "currency": "EUR",
  "salespersonId": "cashier-1",
  "openingFloatCents": 10000,
  "movements": [
    {
      "amountCents": -2500,
      "reason": "Achat fournitures",
      "at": "2026-01-02T11:00:00.000Z"
    }
  ],
  "status": "open",
  "closing": null,
  "actorId": "cashier-1",
  "openedAt": "2026-01-02T09:00:00.000Z"
}

Authorizations

Authorization · string · header · required

Authorization: Bearer <token>. Accepts EITHER a Keycloak access token (scopes-in-token) OR an opaque POS session token; both resolve to the same pos.* scope vocabulary the route guards enforce.

Path Parameters

sessionId · string · required

Id of the register session (session de caisse) to read or transition.

Minimum string length: 1

Body

application/json

amountCents · integer · required

Signed movement in integer cents: positive = pay-in, negative = pay-out; never 0.

Required range: -9007199254740991 <= x <= 9007199254740991

reason · string · required

Human-facing reason for the cash movement (mouvement).

Minimum string length: 1

idempotencyKey · string

Optional client idempotency key; a retried request with the SAME key returns the already-recorded movement instead of double-recording.

Minimum string length: 1

Response

200

application/json

The session with the appended movement.

The session with the appended movement.

id · string · required

storeId · string · required

registerId · string · required

currency · string · required

salespersonId · string · required

openingFloatCents · integer · required

Required range: -9007199254740991 <= x <= 9007199254740991

movements · object[] · required

Show child attributes

status · enum<string> · required

Available options: open, closed

closing · object | null · required

Show child attributes

actorId · string · required

openedAt · string<date-time> · required

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$