The Reconciliation API

Hii InStore does everything through this API, and so can your own client. This page groups the endpoints by what they are for. The API reference has the request and response schemas.

Base URL: https://reconciliation.retailsvc.com

Calls need a Hii Retail IAM token and the permission named for each endpoint below. Paths take the store's businessUnitId, and the till audit's reconciliationId where it applies.

Finding till audits and what to count

Endpoint	Permission	Answers
POST /api/v1/business-units/{businessUnitId}/reconciliations:search?skip=&take=	rec.reconciliations.search	which till audits exist. Filter by status, operatorId, workstationId, reconciliationType, reconciliationDate.
GET /api/v1/business-units/{businessUnitId}/reconciliations/{reconciliationId}/entries	rec.tenders.get	the tenders and items to count in this till audit
GET /api/v1/business-units/{businessUnitId}/reconciliations/{reconciliationId}/sign-in-status	rec.reconciliations.get-sign-in	whether the cashier is still signed in at the till

Counting and approving

Endpoint	Permission	Does
POST /api/v2/business-units/{businessUnitId}/reconciliations/{reconciliationId}/counts:count	rec.counts.count	the cashier's count. Answers APPROVED, REJECTED or LOCKED, with the attempts left.
GET /api/v2/business-units/{businessUnitId}/reconciliations/{reconciliationId}/counts:deviations	rec.counts.get-deviations	the deviation per tender in the latest count, for a locked till audit. Empty unless rec.show-deviation-details-in-till-audit.v1 is on for the store.
GET /api/v1/business-units/{businessUnitId}/reconciliations/{reconciliationId}/counts-deviations	rec.counts.get-deviations	the deviation per tender in the latest count, whatever the status and setting
POST /api/v1/business-units/{businessUnitId}/reconciliations/{reconciliationId}:approve	rec.reconciliations.approve	approves a locked or open till audit, with the explanation in comment
POST /api/v1/business-units/{businessUnitId}/reconciliations/{reconciliationId}:comment	rec.counts.recount	adds or changes the comment on the latest count, spot count or recount, chosen with countType. ⚠ Always send countType: without it, the call also approves an open or locked till audit.

A count is a list of counted tenders, each with an amount, a quantity, or denominations, and a list of counted items. How the answer is decided is in Counting the till.

The store manager's review

Endpoint	Permission	Does
POST /api/v2/business-units/{businessUnitId}/reconciliations/{reconciliationId}/counts:spot	rec.counts.spot	a spot count. Answers whether the drawer is within the limits now, with the deviations.
POST /api/v2/business-units/{businessUnitId}/reconciliations/{reconciliationId}/counts:recount	rec.counts.recount	a recount of a completed till audit, with an optional comment
GET /api/v1/business-units/{businessUnitId}/reconciliations/{reconciliationId}/counts:history	rec.counts.get-history	every count made on the till audit, optionally by countType: COUNT, SPOT or RECOUNT
GET /api/v2/business-units/{businessUnitId}/reconciliations/{reconciliationId}/grouped-counts:deviations	rec.counts.get-deviations	the deviation per shift
GET /api/v1/business-units/{businessUnitId}/reconciliations/{reconciliationId}/cash-report	rec.reconciliations.cash-report	the till audit's cash movements, opening amount, expected and counted amounts

Closing the day

Endpoint	Permission	Does
GET /api/v1/business-units/{businessUnitId}/reconciliations:totals?reconciliationDate=	rec.counts.get-expected	the store's totals per tender for a business date: expected, counted, deviation and the store-level limits
GET /api/v2/business-units/{businessUnitId}/reconciliations/end-of-day:not-submitted	rec.end-of-day.get-not-submit	the business dates whose day has not been submitted yet
POST /api/v1/business-units/{businessUnitId}/end-of-day:submit	rec.end-of-day.submit	submits the day. Body: endOfDayDate and an optional comment.
GET /api/v1/operational-status?from=&to=	rec.end-of-day.get-overview	across stores, each business date's status: error when the day was not submitted, warning when it was submitted with an explanation for a deviation, ok otherwise

The rules for submitting are in Closing the day.

For the POS

Endpoint	Permission	Answers
GET /api/v1/business-units/{businessUnitId}/reconciliations/is-active?workstationId=&operatorId=&date=	rec.reconciliations.status, or a workload identity token with the Tenant-Id header	whether the till or cashier has an open till audit. If not, the answer includes the float to suggest per tender.

Asynchronous effects

A count, an approval, a recount or a day submission is answered at once. The events it leads to, such as reconciliation-completed, and the update of the safe in Cash Management, follow within seconds. Read the results from the events rather than polling. See Receiving the events.