iotoms Docs

Record a customer receipt

POST
/api/v1/receivables/receipts

Records money received from a customer. Send allocations to apply it to specific sales, or omit them to settle the oldest open sales first; any remainder is held as on-account credit.

How to use it

  1. Get the customer number and their open credit sales from Get a customer's outstanding balance.
  2. Send the amount, payment mode and date; add allocations (sale ID plus amount) to choose which sales to settle.
  3. Without allocations the money settles the oldest open sales first; any leftover is kept as on-account credit.
  4. The receipt is saved as POSTED and cannot be edited; to correct it, use Reverse a customer receipt.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Header Parameters

X-TenantID*string

Your merchant's tenant code — the value typed in the Domain field on the iotoms login screen. See Concepts.

Request Body

application/json
  1. body
customerNumber*string

Customer number of the paying customer, from List customers. Required.

amount*number

Amount received in the merchant's currency. Must be greater than zero.

mode*string

How the money was paid: CASH, DIGITAL, CHEQUE, BANK_TRANSFER or OTHER. Required.

Value in"CASH""DIGITAL""CHEQUE""BANK_TRANSFER""OTHER"
receivedOn?|

Date the money was received (YYYY-MM-DD). Defaults to today.

Formatdate
reference?|

Payment reference such as a cheque or bank transfer number.

notes?|

Free-text notes for the receipt.

dayCycleId?|

ID of the van-sales day cycle the money was collected in, if any.

Formatuuid
allocations?array<>|

Sales to apply the money to. Omit or send empty to settle the oldest open sales first; any remainder becomes on-account credit.

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when the request was processed; otherwise an error status.

message*string

Short human-readable message describing the outcome, e.g. which record was saved or why the call failed.

data?

The customer receipt with its allocations.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/receivables/receipts' \  -H 'X-TenantID: your-tenant-code' \  -H 'Content-Type: application/json' \  -d '{  "customerNumber": "string",  "amount": 0,  "mode": "CASH"}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "receiptNumber": "string",    "customerNumber": "string",    "amount": 0,    "allocatedAmount": 0,    "unallocatedAmount": 0,    "mode": "CASH",    "status": "POSTED",    "reference": "string",    "receivedOn": "2019-08-24",    "notes": "string",    "dayCycleId": "bbed7a30-80be-4ccf-810d-a33c370a67d1",    "collectedBy": "string",    "reversalOfId": "91205805-6131-4e22-87c1-99e3bbb30d9b",    "reversalReason": "string",    "allocations": [      {        "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",        "invoiceNumber": "string",        "amount": 0      }    ],    "createdAt": "2019-08-24T14:15:22Z",    "createdBy": "string"  }}