iotoms Docs

Settle an order return

POST
/api/v1/transaction/returns/{returnId}/settlements

Records how a return is paid back: store credit, cash, digital refund or a mix. clientSettlementId is required and makes retries safe. Store credit is issued to the customer, and rejected returns cannot be settled.

How to use it

  1. Take the returnId from Create an order return or List order returns; rejected returns cannot be settled.
  2. Choose settlementMode and send the matching amounts (0 for the rest), plus a unique clientSettlementId so retries do not pay twice.
  3. You can settle in several calls, but the total of all settlements can never exceed the return's grandTotal. Store credit issued when the return was created is not counted towards this limit, so do not settle that part again.
  4. Any storeCreditAmount is added to the customer's store credit (see Get store credit balance) and the return's status becomes SETTLED, even when only part of the amount has been settled so far.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Path Parameters

returnId*string

ID of the return to settle, from Create an order return or List order returns.

Formatuuid

Header Parameters

Request Body

application/json
  1. body
clientSettlementId*string

Required idempotency key. Resending the same key with the same body returns the existing settlement.

settlementMode*string

STORE_CREDIT, CASH or DIGITAL: only that amount may be above zero. MIXED: any combination, with a total above zero.

Value in"STORE_CREDIT""CASH""DIGITAL""MIXED"
storeCreditAmount*number

Required (0 for none). Amount to refund as store credit; needs a customer on the original sale.

refundCashAmount*number

Required (0 for none). Amount refunded in cash, in the merchant's currency.

refundDigitalAmount*number

Required (0 for none). Amount refunded digitally (card, wallet, bank), in the merchant's currency.

refundReference?|

Optional reference for the refund, for example a card refund or transfer ID.

notes?|

Optional free-text notes about the settlement.

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when it worked, ERROR when it failed.

message*string

Short human-readable message describing the outcome, for example "Vendor created". Do not parse it.

data?

The settlement that was recorded (or the existing one when a retry matched).

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/transaction/returns/497f6eca-6276-4993-bfeb-53cbbbba6f08/settlements' \  -H 'Content-Type: application/json' \  -d '{  "clientSettlementId": "string",  "settlementMode": "STORE_CREDIT",  "storeCreditAmount": 0,  "refundCashAmount": 0,  "refundDigitalAmount": 0}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "settlementId": "b4887549-5aec-4adc-bf32-5fb69ede72ea",    "returnId": "251a8eaa-420a-41f0-8ae1-5162d9422d98",    "clientSettlementId": "string",    "settlementMode": "STORE_CREDIT",    "storeCreditAmount": 0,    "refundCashAmount": 0,    "refundDigitalAmount": 0,    "refundReference": "string",    "notes": "string",    "createdBy": "string",    "createdAt": "2019-08-24T14:15:22Z"  }}