Add Transaction

Add Transaction

Lets you add transactions of loyalty, non-loyalty, or not-interested customers. You can add batch transactions by passing each transaction details in a separate transaction attribute.

Rate Limit

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

Currently, there is no validation that bill amount should match with sum of line items as the data is accepted as it is from POS or integration

Following are the key functionalities of the transaction/add API.

  • Registers customers automatically when a new identifier is passed with the transaction details.
  • If any identifier matches with another accounts, customer accounts will be merged if the config mentioned below is not enabled.
  • If 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.
  • Also, this config overrides CONF_PRIMARY_IDENTIFIER_STRICT_CHECK.
  • Updates customer details if a registered identifier is passed with different customer details (other than customer identifiers).
  • Supports transactions with Product Variant and Product Bundle details.
  • Adds product variant to the database when a new variant product is passed with an existing base product.
  • Adds base product to the database when a new base product/variant product is passed. However, if a new base product is passed with variant details, it adds only base product and ignores variant .

Request Body Parameters

ParametersTypeDescription
bill_client_idstringUnique id of the bill as per the client (org) end.
typeEnumType of transaction. regular for loyalty transaction, not_interested for non-loyalty or not-interested transactions.
numberstringUnique transaction number. The uniqueness depends on the configuration CONF_LOYALTY_BILL_NUMBER_UNIQUE_IN_DAYS set on InTouch Settings > System & Deployment > InTouch POS Configuration > Billing.
amountdoubleNet transaction amount of the original bill.
currency_codestringISO currency code of the transaction. For example, INR for Indian Rupee, SGD for Singapore Dollar, EUR for Euro, IQD for Iraqi Dinar.
notesstringAdditional information about the transaction.
qtyintQuantity of the current line-item.
ratefloatPrice of each line-item.
valuedoubleGross transaction amount (transaction amount excluding discount).
billing_timedate-timeDate and time of the transaction. By default, the current system date and time will be considered.
gross_amountdoubleDiscount availed for the transaction (discount amount).
outlier_statusEnumPass the outlier status of the transaction at transaction level, and outlier status of the line-item at line-item level. Values: INTERNAL, NORMAL, INVALID, OUTLIER, FAILED, DELETED, RETRO, FRAUD, TEST, OTHER.
sourceEnumSource 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).
not_interested_reasonstringReason why the customer is not interested to register. Applicable only for not-interested transactions.
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, [727298, 237856].
referral_codestringReferral code for a new customer (if applicable) to register in the org’s loyalty program. You can also have transaction level referral code.
customerobjPass customer information. Applicable for non-loyalty and not-interested transactions.
mobile/email/external_id/card_numberstringPass any of the registered identifiers of the customer. Required for regular transactions.
extended_fieldsobjValid transaction level extended field details in name and value pairs. You can also pass line-item level extended field details in line_item object.
payment_detailsobjPayment details for the transaction.
attributesobjAttributes of the current line-item in name and value pairs.
modestringMode of payment. This has to be the mode configured for your org.
valuefloatAmount paid through the current mode.
custom_fieldsobjTransaction level custom field details. Pass line-item level custom field details in line_item object.
line_itemsobjDetails of transaction line-items.
seriallongSerial number of the current line-item.
transaction_numberstringTransaction line-item number.
descriptionstringDescription of the line-item.
item_codestringUnique line-item code.
variantstringVariant code of the item. Applicable for variant product.
addon_itemsobjDetails of add_on items. For example, pizza with extra cheese, and personalized toppings.
combo_itemsobjDetails of combo or bundle items. For example, buy 1 shirt get one free, shirt+pant, pack of 5 soaps.
split_itemsobjDetails of split items. For example, a necklace having gold rate, store rate, making charge, and wastage charges.
item_codestringUnique code of the add-on, split, or combo item. For example, combo-22, pizza01_addon.
quantitydoubleQuantity of the current add-on, split, or combo item.
associate_detailsobjDetails of store associate or cashier who did the transaction.
codestringUnique code of the store associate.
namestringName of the store associate.

Return Transaction

Lets you submit a return transaction of any transaction type.

The following are different return types supported for a transaction.

Full Return: To return an entire transaction and exchange with different items
Line-item Return: To return line-item(s) of a transaction and exchange with other items
Mixed Return: To exchange one or more line items of a transaction (line-items)
Amount Return: To return the entire transaction amount

📘

For return transactions, it is required to pass return item’s purchased transaction number and purchase_time. Purchase time: The date and time of the actual transaction Billing time: The date and time of the return transaction

Before using this API, you need to know the configurations set of the Return Transactions page of InTouch Settings > Systems & Deployment > InTouch POS Configuration.

Request Body Parameters

ParameterDatatypeDescription
type*enumType of transaction. RETURN for loyalty transaction return, NOT_INTERESTED_RETURN for not-interested return, MIXED for exchange (involves both return and purchase).
You will also need to pass type for MIXED transaction both at bill level (MIXED) and line-item level (regular for new transaction item and return for return item).
return_typeenumType of return. Value: AMOUNT to return transaction or line-items for money, LINE_ITEM to return one or more line-items of the transaction, FULL to return complete transaction.
number*stringActual transaction number of the return bill.
parent_bill_numberstringReturn transaction number.
billing_time*date-timeDate and time of the return transaction in YYYY-MM-DD HH:MM:SS format.
purchase_time*dateActual transaction date of the returning bill inYYYY-MM-DD format.
notesstringAdditional information about the transaction.
amount*doubleSum of regular line items of the current transaction after discount.
qty*intQuantity of the current line-item.
ratefloatPrice of each line-item.
valuefloatGross transaction amount (transaction amount excluding discount).
amount*doubleNet return transaction amount.
sourceenumSource 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).
customerobjCustomer details associated to the transaction. Not applicable for not-interested transactions.
mobile/email/external_idstringPass any of the registered identifiers of the customer. Required for regular transaction returns.
firstnamestringFirst name of the customer.
lastnamestringLast name of the customer.
extended_fieldsobjValid transaction level extended field details in name and value pairs. You can also pass line-item level extended field details in line_item object.
custom_fieldsobjTransaction level custom field details. Pass line-item level custom field details in line_item object.
line_itemsobjDetails of transaction line-items.
seriallongSerial number of the line-item.
descriptionstringDescription of the line-item.
item_codestringUnique line-item code.
variantstringVariant code of the item. Applicable for variant product.
addon_itemsobjDetails of add-on items. For example, pizza with extra cheese, and personalized toppings.
combo_itemsobjDetails of combo or bundle items. For example, buy 1 shirt get one free, shirt+pant, pack of 5 soaps.
split_itemsobjDetails of split items. For example, a necklace having gold rate, store rate, making charge, and wastage charges.
item_codestringUnique code of the add-on, split, or combo item. For example, combo-22, pizza01_addon.
quantitydoubleQuantity of the current add-on, split, or combo item.
associate_detailsobjDetails of store associate or cashier who did the transaction.
codestringUnique code of the store associate.
namestringName of the store associate.
Parameters marked with * are mandatory.

Response Parameters

ParameterDatatypeDescription
idlongUnique transaction ID generated internally.
customerobjDetails of the customer associated to the transaction. Not applicable for NOT_INTERESTED transactions.
lifetime_pointsintTotal loyalty points earned by the customer to date.
lifetime_purchasesintTotal purchases amount (loyalty or non-loyalty transactions) of the customer across all stores of the org.
loyalty_pointsintCurrent active loyalty points (neither redeemed nor expired) of the customer.
typeenumType of transaction. Value: regular for loyalty transaction, not_interested for non-loyalty or not-interested transactions.
sourceenumSource 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).
current_slabstringCurrent loyalty tier of the customer.
tier_expiry_datedate-timeExpiry date of the current tier in YYYY-MM-DD HH:MM:SS format.
points_summariesobjShows the details of the loyalty points.
programIdlongUnique ID of the loyalty program associated to the points summary.
redeemedintIn total points earned from the program, the total number of points that are redeemed.
expiredintIn total points earned from the program, the total number of points that are expired.
returnedintIn total points earned from the program, the total number of points that are returned. Usually, for transaction returns.
adjustedintPoints that are either credited to or debited from the customer account in adjustments. The value will be negative if debited points are more than credited, and positive if credited points are more than debited.
cumulativePurchasesdoubleTotal purchases amount of the customer in the stores associated to the current loyalty program.
currentSlabstringCurrent tier of the customer in the loyalty program.
nextSlabstringNext loyalty tier of the customer.
nextSlabSerialNumberintSerial number of the next tier. Lowest tier will have 1, succeeding tier will have 2 and so on.
nextSlabDescriptionstringDescription of the next tier as saved in the loyalty program.
slabSNointSerial number of the current tier of the customer. Lowest tier will have 1, succeeding tier will have 2 and so on.
slabExpiryDatedate-timeExpiry date of the current loyalty tier of the customer in YYYY-MM-DD HH:MM:SS.
registered_ondate-timeDate on which the customer is enrolled in the org's loyalty.
updated_ondate-timeRecent date on which the customer details are updated.
typeenumLoyalty type of the customer. LOYALTY if the customer is enrolled in the org's loyalty program, NON_LOYALTY if customer has not enrolled in the loyalty program but registered mobile number or email id with the org.
custom_fieldsobjTransaction or line-item level custom field details - field name (name) and field value (value).
extended_fieldsobjTransaction or line-item level extended field details - extended field name (name) and extended field value (value).
Language
Authorization
Basic
base64
:
URL
Click Try It! to start a request and see the response here!