iotoms Docs

Redeem store credit

POST
/api/v1/payments/store-credits/redeem

Spends part of a customer's store credit balance. Fails if the amount exceeds the available balance. A clientRedemptionId makes retries safe; reusing it with different details returns a conflict.

How to use it

  1. Check the available balance with Get store credit balance for the customer (and store, if credit is held per store).
  2. Send customerNumber, a positive amount no larger than the balance, and a clientRedemptionId you generate so retries are safe.
  3. If you send contextType (e.g. POS_ORDER), also send contextId with the ID of that order or visit.
  4. The redemption is recorded in the store credit history and the available balance drops by the amount at once.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Header Parameters

Request Body

application/json
  1. body
clientRedemptionId?|

Your own unique ID for this redemption. Retrying with the same ID and details returns the original; different details return a conflict.

customerNumber*string

Customer account whose store credit is spent. Required.

storeId?|

ID of the customer store, to spend only credit held for that store. Optional.

Formatint64
amount*number

Amount to redeem, in the merchant's currency. Must be positive and not more than the available balance.

contextType?|

What the redemption is for: STORE_VISIT, POS_ORDER or ECOM_DELIVERY (older values DAY_CYCLE, STORE, ORDER_RETURN, TRANSACTION, OTHER also accepted).

Value in"STORE_VISIT""POS_ORDER""ECOM_DELIVERY""DAY_CYCLE""STORE""ORDER_RETURN""TRANSACTION""OTHER"null
contextId?|

ID (a UUID) of the order, visit or other record named in contextType. Required when contextType is sent.

Formatuuid
notes?|

Optional free-text note stored with the redemption.

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when the request worked, ERROR when it did not.

message*string

Short human-readable message describing the result, for logs or display; do not parse it.

data?

The store credit result. See the endpoint description for its exact shape.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/payments/store-credits/redeem' \  -H 'Content-Type: application/json' \  -d '{  "customerNumber": "string",  "amount": 0}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "entryId": "09a8b554-45ca-4bab-a638-265db4b3e828",    "entryType": "ISSUE",    "customerNumber": "string",    "storeId": 0,    "amount": 0,    "contextType": "STORE_VISIT",    "contextId": "84451116-c600-49e2-9c60-5b6b34fae0d6",    "sourceReturnId": "5b288ae1-0cef-4f97-a8fb-6349478b481a",    "clientRedemptionId": "string",    "notes": "string",    "createdBy": "string",    "createdAt": "2019-08-24T14:15:22Z"  }}