The Cash Management 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://cash-management.retailsvc.com

Calls need a Hii Retail IAM token with the permission named for each endpoint, and access to the store. Paths take the store's businessUnitId, and the safe's repositoryId where it applies. Unknown fields in a request body are refused with 400.

Writes are booked a moment later

Bank deposits, withdrawals, corrections and safe audits are accepted by the API and booked a moment later. A 200 means the request was valid and accepted, not that the balance has changed yet. To act on the result, subscribe to the transactions event, or read the balance again after a short wait.

Creating, renaming and deleting a safe take effect at once.

The safe and its balance

Each path starts with /api/v1/business-units/{businessUnitId}.

Endpoint	Permission	Answers / does
POST …/repositories	cmm.repositories.create	create the store's safe: { "name": "Main safe", "type": "Safe" }. type is Safe or CashChanger, one active of each per store. Returns repositoryId.
GET …/repositories	cmm.repositories.get	the store's active repositories, id and name
PATCH …/repositories/{repositoryId}/name	cmm.repositories.update	rename it
DELETE …/repositories/{repositoryId}	cmm.repositories.delete	delete it. Refused with 400 for the store's only safe.
GET …/repositories/{repositoryId}/contents	cmm.repositories.get-content	the balance per currency
GET …/repositories/contents	cmm.repositories.get-content	the total across the store's repositories, per currency
GET …/currencies	cmm.currencies.get	the currencies the store handles: those of its cash tenders, and any currency with a balance

See The safe.

Bank deposits, withdrawals and corrections

Each body is a list of { currencyId, amount, referenceId?, reasonCode? }, one line per currency or bag.

Endpoint	Permission	Does
POST …/repositories/{repositoryId}:bank-deposit	cmm.repositories.bank-deposit; for a negative amount also cmm.repositories.bank-dep-neg	cash from the safe to the bank
POST …/repositories/{repositoryId}:bank-withdrawal	cmm.repositories.bank-withdrawal; for a negative amount also cmm.repositories.bank-withdr-neg	cash from the bank into the safe
POST …/repositories/{repositoryId}:corrections	cmm.repositories.corrections	change the balance by the difference between a count and the balance

A negative bank amount needs a reasonCode. See Bank and corrections.

The safe audit

Endpoint	Permission	Answers / does
GET /api/v2/business-units/{businessUnitId}/repositories/{repositoryId}/audits/audit	cmm.audits.get	the values to audit per currency, the limits, and the store's screen settings and customer-defined fields
POST /api/v2/business-units/{businessUnitId}/repositories/{repositoryId}/audits	cmm.audits.commit	submit the audit. Refused with 400 if the till cash has changed since the GET.
POST /api/v1/business-units/{businessUnitId}/repositories/audits:search?skip=&take=	cmm.audits.search	earlier audits of one safe. Body: repositoryId (required), and createdDateTime or businessDate as { from, to }. Newest first.

See The safe audit.

The history

Endpoint	Permission	Answers
POST …/repositories/transactions:search?skip=&take=	cmm.transactions.search	the store's transactions, newest first. Filter by repositoryId, eventType (a list), referenceId (a bag reference), and createdDateTime or businessDate as { from, to }.
GET …/transactions/event-types	cmm.transactions.get-event-types	the event types that occur in the store's history, including its customer-defined fields. Any of them can be used as a search filter.
GET …/repositories/{repositoryId}/cash-report?businessDate=	cmm.repositories.cash-report	one business date in one safe, per currency: the balance at the start and end of the day, the movements, and the corrections

skip defaults to 0 and take to 10, at most 1 000. The response carries page with total and hasMore. In search results, a transaction that took cash out of the repository you filter on has a negative amount.

The head-office overview

Endpoint	Permission	Answers
GET /api/v1/operational-status?from=&to=	cmm.audits.get-status	for every store and business date in the period that had till cash: whether the safe was audited. error: no safe audit; warning: audited, with a comment explaining a deviation; ok: audited. Add businessUnitId for one store, and doSkipOk, doSkipWarning or doSkipError to leave a status out.

This endpoint covers the whole tenant and is not addressed by store.