Error

A valid request URL is required to generate request examples

{
  "id": "rnt-2030-000184",
  "skuId": "6b1f0c93a4d7e28150c3af6b9d24e70f8a5c1b3e6d90f27a4c8b5e1d3f7a9c02",
  "customerId": "cust-1",
  "storeId": "shop-1",
  "period": {
    "startAt": "2030-01-01T09:00:00.000Z",
    "dueAt": "2030-01-04T09:00:00.000Z"
  },
  "days": 3,
  "ratePerDayCents": 640,
  "depositAmountCents": 4000,
  "depositReference": "PREAUTH-4821",
  "status": "returned",
  "actorId": "user-associate-1",
  "rentedAt": "2030-01-01T09:00:00.000Z",
  "settlement": {
    "returnedAt": "2030-01-06T09:00:00.000Z",
    "condition": "dommage",
    "lateFeeCents": 1920,
    "damageRetentionCents": 1500,
    "releasedDepositCents": 2500
  }
}

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "statusCode": 123,
    "fieldErrors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

Rentals

Return a rental and settle the caution

IRREVERSIBLE CLOSE-OUT. Takes the unit back, flips the rental to returned (terminal — there is no un-return, no re-open and no way to amend a settlement afterwards) and stamps the settlement. Legal from active AND from overdue; a second call on an already-returned rental is 422. condition is your assessment: {"kind":"conforme"} releases the whole caution, {"kind":"dommage","retentionCents":N} retains N cents of it and releases the rest. Only send dommage on a damage assessment a human actually made — you are deciding to keep a customer’s money. TWO MONEY TRAPS. (1) retentionCents is SILENTLY CLAMPED to depositAmountCents: ask for more than the caution and you get a 200 with the caution retained in full and no warning, so always compare the returned settlement.damageRetentionCents against what you sent. (2) settlement.lateFeeCents (ratePerDayCents x 1.5 x whole days past dueAt, any part of a day counting as a full one) is REPORTED, not collected: it is NOT deducted from the caution and releasedDepositCents is deposit - retention alone, so a late conforme return releases the entire caution while still owing a fee. Surface a non-zero lateFeeCents to the operator — nothing else in this API will charge it. The release/retention itself is executed by the payment terminal against depositReference, not by this call. 404 for an unknown id. NOT IDEMPOTENT — there is no dedup key. A SEQUENTIAL replay cannot settle twice (the status guard rejects it), but that guard is an unsynchronised read-then-write with no row lock, so two CONCURRENT returns can both pass it and both settle — never fan this out. If your call times out RE-READ with getRental before retrying: a returned status means the first attempt already committed, and the settlement you see is the only one there will ever be — never assume a retry produced a fresh one. See solya-pos#956 for the missing lockKeys.

POST

rentals

{rentalId}

return

Error

A valid request URL is required to generate request examples

{
  "id": "rnt-2030-000184",
  "skuId": "6b1f0c93a4d7e28150c3af6b9d24e70f8a5c1b3e6d90f27a4c8b5e1d3f7a9c02",
  "customerId": "cust-1",
  "storeId": "shop-1",
  "period": {
    "startAt": "2030-01-01T09:00:00.000Z",
    "dueAt": "2030-01-04T09:00:00.000Z"
  },
  "days": 3,
  "ratePerDayCents": 640,
  "depositAmountCents": 4000,
  "depositReference": "PREAUTH-4821",
  "status": "returned",
  "actorId": "user-associate-1",
  "rentedAt": "2030-01-01T09:00:00.000Z",
  "settlement": {
    "returnedAt": "2030-01-06T09:00:00.000Z",
    "condition": "dommage",
    "lateFeeCents": 1920,
    "damageRetentionCents": 1500,
    "releasedDepositCents": 2500
  }
}

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "statusCode": 123,
    "fieldErrors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

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

rentalId

string

required

Minimum string length: 1

Body

application/json

condition

object

required

Option 1
Option 2

Show child attributes

Response

The closed-out rental: returned, with the settlement stamped. In this example the unit came back two days late and damaged, so 1500 cents were retained, 2500 released, and 1920 cents of late fee are OWED but not taken.

string

required

skuId

string

required

customerId

string

required

storeId

string

required

period

object

required

Show child attributes

days

required

Available options:

1

ratePerDayCents

integer

required

Required range: -9007199254740991 <= x <= 9007199254740991

depositAmountCents

integer

required

Required range: -9007199254740991 <= x <= 9007199254740991

depositReference

string

required

status

enum<string>

required

Available options:

active,

returned,

overdue

actorId

string

required

rentedAt

string

required

settlement

object

Show child attributes

Flag a rental as overdue List repair orders

Ventes & encaissement

Catalogue & stock

Finance

Clients & fidélité

Marketing & promotions

Services

Système

Other

Return a rental and settle the caution

Authorizations

Path Parameters

Body

Response