Add/Return Transaction(bulk)

Lets you add or return one or more transactions to the Capillary system. It supports both loyalty and not-interested transactions.

CONFIG_SKIP_SECONDARY_ID_ON_PRIMARY_MISMATCH is enabled: If the primary identifier is different but any of the secondary identifiers exist, a new customer is registered with the primary identifier ignoring the secondary identifier. The config is available on the Registration Page of InTouch Profile > Organization Settings > Miscellaneous.

👍

Notes

  • To avoid any confusion related to 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.
  • You cannot register a customer with this API. Hence, you need to pass only registered identifiers for regular transactions.

Rate Limit

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

Request Body Parameters

ParameterTypeDescription
identifierType*EnumPass any of the registered identifier name of the customer.
Values: mobile, email, externalId, wechat, martjackId, or fbId (Facebook ID), id.
identifierValue*stringPass the respective identifier value.
For example if identifierType is mobile, identifierValue is mobile number.
source*EnumPass 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.
type*EnumType of transaction.
Supported value: REGULAR for loyalty transactions. RETURN for return transactions. NOT_INTERESTED, NOT_INTERESTED_RETURN.
notInterestedReasonstringNotes on why the customer is not interested to enroll into the loyalty (type=NOT_INTERESTED).
Max characters supported - 255.
returnType**EnumFor a return transaction, pass the return type.
Value: AMOUNT, FULL, LINE_ITEM, CANCELLED.
billNumber*stringUnique transaction number. For a return transaction, this is the original transaction number of the return item. In transaction add the uniqueness of the billNumber is either at till, store, or org, depends on the configuration.
Note: The maximum length for a bill number is 50 characters.
idlongTransaction ID of the transaction that needs to be returned.

Identifies the specific transaction to be returned when identical bill numbers exist across different transactions.
This is applicable when the CONF_LOYALTY_BILL_NUMBER_UNIQUE_ONLY_STORE configuration is enabled, and the same bill number is used for transactions at different stores.
Example:
Store A: Customer transaction with bill number B1
Store B: Different transaction also with bill number B1
In this scenario, you can include the transaction ID in the return transaction payload to:

- Distinguish between transactions with identical bill numbers
- Prevent failures in return transactions due to duplicate bill numbers
billAmount*doubleNet 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.
Values: PLACED, PROCESSED, SHIPPED, DELIVERED, RETURNED.
You can update the status using v2/transaction/update.
userGroup2IdintUnique ID of the user group to which the transaction needs to be associated with.
Any one among the parameters with userGroup2 is required to associate the transaction with a group.
userGroup2PrimaryUserIdlongUnique user ID of the primary member of group to which the transaction needs to be associated with.
userGroup2ExternalIdstringUnique external ID of the user group to which the transaction needs to be associated with.
userGroup2PrimaryUserIdentifierTypeEnumIdentifier type used to identify group primary member.
Value: mobile, email, externalId, wechat, martjackId, or fbId (Facebook ID), id.
userGroup2PrimaryUserIdentifierValuestringValue of the specified group identifier type.
userGroup2PrimaryUserSourceEnumSource in which the identifier of the group primary member is registered.
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).
userGroup2PrimaryUserAccountIdstringAccount ID for sources with multiple accounts such as WECHAT.
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.
purchaseTime*date-timeBilling time of regular transactions, for which a return is happening 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.
extendedFieldsobjValid transaction level extended field details in name and value pairs.
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.

Attribution Object

ParameterTypeDescription
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.
Value: ZONE, CONCEPT, STORE, TILL, STR_SERVER, ADMIN_USER, ASSOCIATE, RULE, OU.

lineItemsV2 object

ParameterTypeDescription
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.
returnableDaysintMaximum number of days the item is allowed to return.
customFieldsobjTransaction or line-item level custom field details.
imgUrlstringURL of the product image.
attributesobjDetails of combo, bundle, or split items.
comboDetailsobjDetails of combo, bundle, or split items.
addOnDetailsobjDetails of add-on items.
splitDetailsobjDetails of split item.
parentBillNumberstringReturn transaction number/Actual transaction number of the return item. Applicable only for mixed transaction (involves both transaction and return).
purchaseTime*date-timeBilling time of regular transactions, for which a return is happening in ISO 8601 standard - YYYY-MM-DDTHH:MM:SSZ
returnTypeEnumReturn type of the line item.
Value: AMOUNT, FULL, LINE_ITEM. Not applicable if the transaction level returnType is FULL or AMOUNT.
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).
appliedPromotionIdentifiersarrayBased 64 encoded format Cart or catalog promotions 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"}
extendedFieldsobjValid transaction line-item level extended field details.

Redemptions Object

ParameterTypeDescription
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

ParameterTypeDescription
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.

📘

Note:

Custom fields can only be used at the customer, bills, and redemption levels; only extended fields are supported at the line item level.

Language
URL
Click Try It! to start a request and see the response here!