Add/Return transaction (single)

Lets you add a new transaction or return an existing transaction. It supports both loyalty and not-interested transactions.

Rate Limit

RegionDefault Limit (RPM)
Asia-2 (Singapore)1500
Asia-1 (N. Virginia)1500
EMEA (Ireland)700



To avoid misunderstandings arising from timezone conversion, you can raise a ticket and enable the CONF_ORG_DISABLE_MACHINE_TIME_CONV configuration. When the configuration is enabled, the time from the payload, without the UTC offset, is stored in the database for all clusters. For more information, refer to the documentation here.

Request Query Parameters

identifierName*EnumPass any of the registered identifier name of the customer.
Values: mobile, email, externalId, id, wechat, martjackId, fbId (Facebook ID), cardnumber, cardExternalId.
identifierValue*stringPass the respective identifier value. For example if identifierType is mobile, identifierValue is mobile number.
sourceEnumPass the source from which the transaction is made. Values: INSTORE(for InStore), WECHAT (WeChat), MARTJACK(AnywhereCommerce), WEB_ENGAGE (Web-engage integration), ECOMMERCE (ECOMMERCE), JD (JD), TAOBAO (Taobao), TMALL (TMall), FACEBOOK (Facebook), WEBSITE (other website), OTHERS (any other source).
accountIdstringFor sources with multiple accounts (such as MARTJACK, WECHAT), pass the respective account ID. Not applicable for INSTORE source.
use_asynchbooleanPass true to run Loyalty activities in the background, side effects will not be returned in the API response. If false, API will wait for Loyalty activities to complete and then respond to the client with side effects in the API response.
rawSideEffectsbooleanPass true to get complete details of incentives such as awardOn, expiryDate, strategyIds and so on.

Request Body Parameters

extendedFieldsobjValid transaction level extended field details in name and value pairs.
type*EnumType of transaction.
Supported value: REGULAR for loyalty transactions. RETURN for return transactions. NOT_INTERESTED, NOT_INTERESTED_RETURN.
returnType**EnumFor a return transaction, pass the return type.
notInterestedReasonstringNotes on why the customer is not interested to enroll into the loyalty (type = NOT_INTERESTED).
Max characters supported - 255.
billNumber*stringUnique transaction number for normal or mixed transactions and original transaction number for return transactions.
billAmountdoubleNet transaction amount.
billingDatedate-timeDate and time of the transaction in the ISO 8601 format - YYYY-MM-DDTHH:MM:SSZ.
discountdoubleDiscount availed for the transaction or line item (discount amount).
grossAmountdoubleTransaction amount before discount.
outlierStatusEnumTransaction level outlier status.
Values: NORMAL, INTERNAL, FRAUD, OUTLIER, TEST, DELETED, FAILED, OTHER. This overrides the outlier status of the configured outlier settings.
notestringAdditional information about the transaction.
deliveryStatusEnumDelivery status of the item.
You can update the status using v2 PUT /transactions
userGroup2IdintExternal ID of the user group to be associated with the transaction. Any one among the parameters with userGroup2 is required to associate the transaction with a group.
userGroup2PrimaryUserIdlongID of the primary user of the group to be associated with the transaction.
userGroup2ExternalIdstringExternal ID of the user group to be associated with the transaction.
currencyCodestringISO currency code of the transaction to add transaction with local currency. For example, INR for Indian Rupee, SGD for Singapore Dollar, EUR for Euro, IQD for Iraqi Dinar. Pass the currency code that are supported for your org (InTouch > Organization Setup) and ensure the currency conversion ratio is set using v2/currencyratio.
addWithLocalCurrencybooleanPass true to add a transaction in local currency.
customFieldsobjDetails of transaction level or transaction line-item level custom fields.
purchaseTimedate-timeActual date of transaction of the returning bill in Date and time of the transaction in ISO 8601 standard - YYYY-MM-DDTHH:MM:SSZ.
promotionEvaluationIdstringPromotion evaluation code (cart/catalog) applied for the transaction.
appliedPromotionIdentifiersarrayBase 64 encoded string of Cart/catalog promotion identifiers that are applied to the transaction.
It will have the details mentioned here {"promotionId":"612e5c5e4133b56abe0f073e","discount":"1000.000000","amount":"3000.000000","discountAppliedQty":"1","promotionAppliedQty":"3.000000","redemptionCount":1,"sku":"JNSREG02","version":"v1"}
loyaltyPromotionIdentifiersarrayIdentifier(s) of loyalty promotion(s) that you want to tag to the transaction.
lineitemsV2objDetails of line items.
attributionobjMapping to tag the transaction to a different user or till (other than the current user).
redemptionsobjDetails of points and coupon redemptions for the transaction.
paymentModesobjPayment details used for the transaction.

lineitemsV2 Object

amountdoubleNet line item amount.
Value - discount = amount.
descriptionstringOne or two liner description of the line-item.
discountintDiscount received on the line item.
itemCodestringUnique code of the transaction line-item.
qtydoubleQuantity of the current line item.
ratedoublePrice of each line item.
serialstringSerial number of the line-item.
valuedoubleGross amount of the item.
Usually, rate*qty = value.
returnablebooleanPass true if the item can be returned post purchase.
reutrnableDaysintMaximum number of days the item is allowed to return.
customFieldsobjTransaction or line-item level custom field details.
imgUrlstringURL of the product image.
attributesobjAttributes of the product in name-value pairs.
addOnDetailsobjDetails add-on item.
splitDetailsobjDetails of split item.
parentBillNumberstringReturn transaction number. Applicable only for mixed transaction (transaction that involves both purchase and return - exchange).
purchaseTimedate-timeActual date of transaction of the return item in ISO 8601 format - YYYY-MM-DDTTHHSSZ.
returnTypeEnumReturn type of the line item.
typeEnumType of the line item. Value: REGULAR (for regular line item purchase), NOT_INTERESTED (for line item purchase with no customer tagging), RETURN (to return a regular line item ), NOT_INTERESTED_RETURN (to return a line item of no-interested transaction).
appliedPromotionIdentifiersarrayCart or catalog promotions applied to the transaction.
extendedFieldsobjValid transaction line-item level extended field details.
comboDetailsobjDetails combo, bundle, or split items.

comboDetails object

itemCodestringUnique line-item code.
quantitydoubleQuantity of the current combo item.
descriptionstringOne or two liner description of add-on, split, or combo item.
ratedoublePrice of the combo item.
valuedoubleItem price excluding discount.
comboTypestringType of the combo. COMBO_PARENT, COMBO_ITEM, ADD_ON_ITEM, SPLIT.

attribution Object

createDatedate-timeDate of the transaction in ISO 8601 standard format.
createdByobjUser ID or store entity (like TILL ID, store ID) associated with the transaction.
  codestringUnique code of the entity.
  typeEnumType of the attribution entity.

redemptions Object

pointsRedemptionsarrayUnique points redemption id(s) that you want to apply for the transaction. For example, [727272, 237878]
couponRedemptionsarrayUnique coupon redemption id(s) that you want to apply for the transaction. For example, [727272, 237878]

paymentModes Object

modestringMode of payment.
valuedoubleAmount paid through the current mode.
notesstringAdditional information related to the payment mode. Max characters - 250.
attributesobjAttributes of the payment mode as name-value pairs.

Error codes

Error codeCauseSolution
Time mismatch between billing time and response timeTime conversion is not disabled.Enable the CONF_ORG_DISABLE_MACHINE_TIME_CONV configuration. When the configuration is enabled, the time from the payload, without the UTC offset, is stored in the database for all clusters. For more information, refer to the documentation here.
624: Invalid return transaction time, Return transaction should happen after add transactionIncomplete body parametersParameter purchaseTime should be passed in the body.
Click Try It! to start a request and see the response here!