Setting up Returns Tracking

Set up the returns tracking server side API to deduct points when an order is partially or fully returned.

The loyalty program awards points for purchases. When an order is returned, the points should be deducted from the user's account.

The Returns Tracking API passes the data for each return to Zinrelo. These returns are correlated against an earlier corresponding purchase. This Returns Tracking API enables Zinrelo to deduct points for returned purchases. This API is typically called from the server-side when the return transaction is created.

Returns API

The API call is an HTTP POST request to this URL:

POST https://help.zinrelo.com/reference/return-points

Click here for detailed documentation regarding this API.

API Authentication

All API calls have to be authenticated with your API key and partner ID. The API key and partner ID are automatically generated for you when your Zinrelo account is created. These can be found in your Zinrelo admin console under the General >> Settings section.

Setting up Returns TrackingSetting up Returns Tracking

For authenticating an API call, you have to send your Partner ID, and an API Key in the HTTP header of each API request.

Send the keys in the HTTP header of each API request as given below:

'api-key': '<your-api-key'
'partner-id' : '<your-partner-id>'

Calling the Returns API

Shown below is a sample Python script to call the Zinrelo Returns API.

import requests
import json

headers = {'partner-id': 'cad458dc4e',
           'api-key': 'c921e097e6679d21c0cad26a45bfec20'}

payload = { 
       "order_id=75a2726d13artibb10",
       "returned_amount = 26.95",
       "returned_product_id = 1234df",
       "quantity = 1"}

response = requests.post(url = "https://help.zinrelo.com/reference/create-a-return-transaction",
                        headers = headers, data = payload)

Here is a description of the query parameters used in the payload of the Returns API call.

ParametersTypeMandatoryDescription
member_idstringYesUnique Identifier (Member ID) for the member object in the client’s system which was used while creating a member in Zinrelo.
transaction_attributesjsonYesApart from the above parameters, you have to pass on custom attributes for return activities. Some are pre-defined attributes such as reason and tags, which are common for all activities. In addition to this, you have the ability to define custom attributes against each activity with the parameters like order_id (required field), returned_amount, returned_product_id and returned_product_quantity.

JSON Response

Here is the sample JSON structured response that you will receive from Zinrelo.

{
  "data":{
          "user_email": "[email protected]",
          "last_name": "John",
          "first_name": "Doe",
          "points": 270,
          "points_status": "pending_deduction",
          "returned_for_order_id": "75a2726d13artibb10",
          "reason": "Order Fully Returned",
          "created_time": "30-Mar-16 19:20:22"
    },
  "success":true
}

Expected Result

Zinrelo will respond with standard HTTP success or failure codes. In case of a success response, the return transaction will reflect in the customer's account in the Zinrelo admin console.

Error Handling

For failures, Zinrelo will also include extra information about what went wrong, encoded in the response as JSON. The various HTTP and API status codes that Zinrelo returns are listed below.

Standard HTTP status codes:

CodeTitleDescription
200OkThe request was successful.
400Bad RequestBad request.
401UnauthorizedYour API key is invalid.
404Not FoundThe resource does not exist.
500Internal Server ErrorAn error occurred with our API.
503Service UnavailableService Unavailable.

Zinrelo API Status Codes:

Status CodeError CodeMessage
200UNABLE_TO_UPLOAD_PHOTOUnable to upload the photo. Please try again later.
400ATTRIBUTE_NOT_UNIQUEIdParams name passed is not a unique attribute.
200MEMBER_ID_ALREADY_IN_USEMember ID already in use.
200INVALID_MEMBER_STATUSInvalid member status.
200MEMBER_BLOCKEDMember has been blocked.
200MAX_AWARDS_EXCEEDEDMaximum award limit exceeded.
200INVALID_AMOUNT_TO_DEDUCTNot enough points to deduct.
400INVALID_JSONInvalid JSON format.
400INVALID_REQUESTInvalid request: unsupported Content-Type [content-type].
200INCORRECT_MEMBER_ID_PASSEDIncorrect Member ID passed.
200STORE_INACTIVEStore is not active.
200MEMBER_DELETEDMember record has been deleted.
200EXCLUDED_TRANSACTIONPoints could not be awarded because exclusion rule was applied.
404TRANSACTION_DOES_NOT_EXISTTransaction does not exist.
500INTERNAL_SERVER_ERRORInternal server error.
400INVALID_REQUEST_PARAMETER_VALUESInvalid request parameter value.
200INVALID_PHOTOInvalid file type or file size. Please make sure uploaded file type is JPG, JPEG, or PNG. and file size should be less than 10MB.
200PAUSED_ACTIVITYActivity is in paused state.
400ID_PARAM_NAME_NOT_FOUNDIdParams name passed does not exist.
401ERROR_UNAUTHORIZEDSome error occurred while authenticating your account at Zinrelo. Please verify your API credentials.
200DUPLICATE_ORDER_IDLoyalty Points already awarded for the Order ID.
200MEMBER_CREATION_UNSUCCESSFULMember creation unsuccessful.
400MERCHANT_DOES_NOT_EXISTMerchant does not exist.
200TRANSACTION_ATTRIBUTE_NOT_UNIQUEUnique transaction attribute for given activity is not unique.
200INVALID_MEMBERMember does not exist.
400INVALID_CURSORInvalid start cursor provided
503SERVICE_UNAVAILABLEAPI Service is unavailable. Please contact Zinrelo support.
200INACTIVE_REWARDThis reward is inactive and cannot be redeemed.
200AUTO_REDEEMABLE_REWARDCannot redeem auto redeemable reward via API.
200INVALID_REWARD_FOR_USERReturned product quantity exceeds order quantity.
200MAX_REWARDS_EXCEEDEDMaximum redemption threshold for reward reached.
200INSUFFICIENT_REDEEMABLE_POINTSUser points balance insufficient.
200INVALID_REWARD_FOR_TIERThis reward is not valid for user tier.
200ORDER_NOT_EXISTOrder with this id does not exist.
200PRODUCT_QUANTITY_EXCEEDEDReturned product quantity exceeds order quantity.
200INVALID_PRODUCT_IDIncorrect product id passed.
200RETURN_VALUE_EXCEEDS_AVAILABLE_BALANCEReturned order value exceeds user's points balance.
200PRODUCT_ID_AND_RETURN_AMOUNT_PASSEDPlease pass either returned product id or returned amount.

The error handling code should log the error response. If you need to look into why a return transaction was not processed, the logs will provide that information easily.


Did this page help you?