iotoms Docs

Create an order return

POST
/api/v1/transaction/returns

Records a return against an existing sale. Returned stock is put back into inventory, and any storeCreditAmount is issued to the customer. A clientReturnId makes retries safe; the return total cannot exceed what is still returnable on the sale.

How to use it

  1. Find the sale with List transactions or Get a transaction, then call Get returnable lines for a transaction to see what can still be returned.
  2. Send transactionId, returnDate, reasonCode, totals (grandTotal = subtotal - discountTotal + taxTotal) and one line per item; set a clientReturnId so retries are safe.
  3. Set storeCreditAmount above 0 to credit the customer immediately; the sale must have a customer. Send 0 to refund later with Settle an order return.
  4. The return is saved as APPROVED: stock goes back to the stockroom it was sold from (damaged, expired or quality returns go to quarantine) and back-office users are notified.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Header Parameters

Request Body

application/json
  1. body
transactionId*string

Required. ID of the original sale, from List transactions or Get a transaction. Unpaid sales cannot be returned.

Formatuuid
clientReturnId?|

Optional idempotency key. Resending the same key with the same body returns the existing return; a different body is rejected as a conflict.

returnDate*string

Required. Date the goods came back (YYYY-MM-DD).

Formatdate
reasonCode*string

Required. Overall reason for the return. Reason code: DAMAGED, EXPIRED, WRONG_ITEM, QUALITY_ISSUE, CUSTOMER_CHANGED_MIND, PRICING_DISPUTE, ORDER_CANCELLATION or OTHER.

reasonNote?|

Optional free-text explanation of the overall reason.

subtotal*number

Required. Value of returned goods before discount and tax, in the merchant's currency. Zero or more.

taxTotal*number

Required. Tax on the returned goods, in the merchant's currency. Zero or more.

discountTotal*number

Required. Discount on the returned goods, in the merchant's currency. Zero or more.

grandTotal*number

Required. Must equal subtotal - discountTotal + taxTotal, be above zero and not exceed the sale's remaining returnable amount.

storeCreditAmount*number

Required (send 0 for none). Part of grandTotal to issue as store credit now; needs a customer on the sale.

reasonBreakdowns*array<>

Required (may be empty). Reasons per item or group of items.

lines*array<>

Required. Items returned. Returned stock goes back to the stockroom it was sold from, or to quarantine for damaged/expired/quality reasons.

syncStatus?|

Optional sync marker from your client (for example an offline device's sync state). Stored as sent.

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 order return with its lines, reasons and latest settlement.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/transaction/returns' \  -H 'Content-Type: application/json' \  -d '{  "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",  "returnDate": "2019-08-24",  "reasonCode": "string",  "subtotal": 0,  "taxTotal": 0,  "discountTotal": 0,  "grandTotal": 0,  "storeCreditAmount": 0,  "reasonBreakdowns": [    {      "scope": "ITEM",      "referenceKey": "string",      "reasonCode": "string"    }  ],  "lines": [    {      "itemId": "string",      "quantity": 0,      "unitPrice": 0,      "discountAmount": 0,      "taxAmount": 0,      "lineSubtotal": 0,      "lineTotal": 0,      "reasonCode": "string"    }  ]}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "returnId": "251a8eaa-420a-41f0-8ae1-5162d9422d98",    "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",    "clientReturnId": "string",    "channel": "LINE_DISTRIBUTION",    "businessDate": "2019-08-24",    "dayCycleId": "bbed7a30-80be-4ccf-810d-a33c370a67d1",    "registerId": 0,    "returnDate": "2019-08-24",    "reasonCode": "string",    "reasonNote": "string",    "subtotal": 0,    "taxTotal": 0,    "discountTotal": 0,    "grandTotal": 0,    "storeCreditAmount": 0,    "reasonBreakdowns": [      {        "scope": "ITEM",        "referenceKey": "string",        "reasonCode": "string",        "reasonNote": "string",        "quantity": 0      }    ],    "lines": [      {        "itemId": "string",        "description": "string",        "quantity": 0,        "unitPrice": 0,        "discountAmount": 0,        "taxAmount": 0,        "lineSubtotal": 0,        "lineTotal": 0,        "reasonCode": "string",        "reasonNote": "string",        "batchNumber": "string",        "expiryDate": "2019-08-24"      }    ],    "settlement": {      "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"    },    "status": "DRAFT",    "syncStatus": "string",    "createdBy": "string",    "createdAt": "2019-08-24T14:15:22Z"  }}