Add Transaction

post https://{host}/v1.1/transaction/add

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

Region	Default 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.
For Multi Loyalty Programs, points can be grouped by their respective program IDs and correctly reflected in the side effects section of the response. To enable this, raise a JIRA ticket with the Sustenance team to activate the configuration CONF_ENABLE_GROUP_POINTS_BY_PROGRAM for your org.

Request Body Parameters

Parameters	Type	Description
bill_client_id	string	Unique id of the bill as per the client (org) end.
type	Enum	Type of transaction. `regular` for loyalty transaction, `not_interested` for non-loyalty or not-interested transactions.
number	string	Unique transaction number. The uniqueness depends on the configuration `CONF_LOYALTY_BILL_NUMBER_UNIQUE_IN_DAYS` set in InTouch Settings > System & Deployment > InTouch POS Configuration > Billing. Note: The maximum length for a bill number is 50 characters.
amount	double	Net transaction amount of the original bill. Represents the final amount after discounts are applied. For line items: amount = value - discount. For transactions: amount = gross_amount - total_discount
discount	double	Discount availed for the transaction or line item (discount amount).
currency_code	string	ISO currency code of the transaction. For example, `INR` for Indian Rupee, `SGD` for Singapore Dollar, `EUR` for Euro, `IQD` for Iraqi Dinar.
notes	string	Additional information about the transaction.
qty	int	Quantity of the current line-item. This gets rounded off to the nearest digit. For example, the quantity "0.003" can get rounded off to 0. It is recommended to use V2 API to avoid the rounding off quantity.
rate	float	Price of each line-item.
value	double	Represents the pre-discount total for a single line item. alculated as: value = rate × quantity. Example: If a line item has a rate of $10 and quantity of 2, value would be $20.
billing_time	date-time	Date and time of the transaction. By default, the current system date and time will be considered.
gross_amount	double	Represents the total transaction amount before any discounts are applied. It's the sum of all line items' values before discounts. Used in calculations involving the total transaction value.
outlier_status	Enum	Pass 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`.
source	Enum	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).
not_interested_reason	string	Reason why the customer is not interested to register. Applicable only for not-interested transactions.
pointsRedemptions	array	Unique points redemption id(s) that you want to apply for the transaction. For example, `[727272, 237878]`.
couponRedemptions	array	Unique coupon redemption id(s) that you want to apply for the transaction. For example, `[727298, 237856]`.
referral_code	string	Referral code for a new customer (if applicable) to register in the org's loyalty program. You can also have transaction level referral code.
customer	obj	Pass customer information. Applicable for non-loyalty and not-interested transactions.
mobile/email/external_id/card_number	string	Pass any of the registered identifiers of the customer. Required for regular transactions.
extended_fields	obj	Valid 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_details	obj	Payment details for the transaction.
attributes	obj	Attributes of the current line-item in name and value pairs.
mode	string	Mode of payment. This has to be the mode configured for your org.
value	float	Amount paid through the current mode.
custom_fields	obj	Transaction level custom field details. Pass line-item level custom field details in `line_item` object.
line_items	obj	Details of transaction line-items.
serial	long	Serial number of the current line-item.
transaction_number	string	Transaction line-item number.
description	string	Description of the line-item.
item_code	string	Unique line-item code.
variant	string	Variant code of the item. Applicable for variant product.
addon_items	obj	Details of add_on items. For example, pizza with extra cheese, and personalized toppings.
combo_items	obj	Details of combo or bundle items. For example, buy 1 shirt get one free, shirt+pant, pack of 5 soaps.
split_items	obj	Details of split items. For example, a necklace having gold rate, store rate, making charge, and wastage charges.
item_code	string	Unique code of the add-on, split, or combo item. For example, combo-22, pizza01_addon.
quantity	double	Quantity of the current add-on, split, or combo item.
associate_details	obj	Details of store associate or cashier who did the transaction.
code	string	Unique code of the store associate.
name	string	Name 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.

📘
Note
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 (Return Transaction)

Parameter	Datatype	Description
type*	enum	Type 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_type	enum	FULL - Returns the full amount of the original transaction. AMOUNT - Returns the specific amount passed in the amount parameter. LINE_ITEM - Returns the amount based on items listed in the line_item object
number*	string	Actual transaction number of the return bill.
parent_bill_number	string	Return transaction number.
billing_time*	date-time	Date and time of the return transaction in `YYYY-MM-DD HH:MM:SS` format.
purchase_time*	date	Actual transaction date of the returning bill in`YYYY-MM-DD` format.
notes	string	Additional information about the transaction.
amount*	double	Amount that needs to be returned.
qty*	int	Quantity of the current line-item.
rate	float	Price of each line-item.
value	float	Gross transaction amount (transaction amount excluding discount).
source	enum	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).
customer	obj	Customer details associated to the transaction. Not applicable for not-interested transactions.
mobile/email/external_id	string	Pass any of the registered identifiers of the customer. Required for regular transaction returns.
firstname	string	First name of the customer.
lastname	string	Last name of the customer.
extended_fields	obj	Valid 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_fields	obj	Transaction level custom field details. Pass line-item level custom field details in `line_item` object.
line_items	obj	Details of transaction line-items.
amount*	double	Net line item amount including tax.
serial	long	Serial number of the line-item.
description	string	Description of the line-item.
item_code	string	Unique line-item code.
variant	string	Variant code of the item. Applicable for variant product.
addon_items	obj	Details of add-on items. For example, pizza with extra cheese, and personalized toppings.
combo_items	obj	Details of combo or bundle items. For example, buy 1 shirt get one free, shirt+pant, pack of 5 soaps.
split_items	obj	Details of split items. For example, a necklace having gold rate, store rate, making charge, and wastage charges.
item_code	string	Unique code of the add-on, split, or combo item. For example, combo-22, pizza01_addon.
quantity	double	Quantity of the current add-on, split, or combo item.
associate_details	obj	Details of store associate or cashier who did the transaction.
code	string	Unique code of the store associate.
name	string	Name of the store associate.

Parameters marked with * are mandatory.

{
    "root": {
        "transaction": {
            "type": "return",
            "country": "true",
            "number": "test00transact112",
            "return_type": "LINE_ITEM",
            "parent_bill_number": "returnBill112",
            "purchase_time": "2025-08-07 10:32:15",
            "amount": "3000.00",
            "billing_time": "2025-08-07 10:34:00",
            "customer": {
                "mobile": "919999988886",
                "email": "[email protected]",
                "external_id": "0000011110",
                "firstname": "Tjuser",
                "lastname": "Eightysix"
            },
            "line_items": {
                "line_item": [
                    {
                        "serial": "2",
                        "amount": "2000",
                        "description": "Sports Shoes",
                        "item_code": "model_id_002",
                        "qty": "2",
                        "rate": "1000.00",
                        "value": "2000.00"
                    } 
                ]
            }
        }
    }
}

Response Parameters

Parameter	Datatype	Description
id	long	Unique transaction ID generated internally.
customer	obj	Details of the customer associated to the transaction. Not applicable for `NOT_INTERESTED` transactions.
lifetime_points	int	Total loyalty points earned by the customer to date.
lifetime_purchases	int	Total purchases amount (loyalty or non-loyalty transactions) of the customer across all stores of the org.
loyalty_points	int	Current active loyalty points (neither redeemed nor expired) of the customer.
type	enum	Type of transaction. Value: `regular` for loyalty transaction, `not_interested` for non-loyalty or not-interested transactions.
source	enum	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).
current_slab	string	Current loyalty tier of the customer.
tier_expiry_date	date-time	Expiry date of the current tier in `YYYY-MM-DD HH:MM:SS` format.
points_summaries	obj	Shows the details of the loyalty points.
programId	long	Unique ID of the loyalty program associated to the points summary.
redeemed	int	In total points earned from the program, the total number of points that are redeemed.
expired	int	In total points earned from the program, the total number of points that are expired.
returned	int	In total points earned from the program, the total number of points that are returned. Usually, for transaction returns.
adjusted	int	Points 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.
cumulativePurchases	double	Total purchases amount of the customer in the stores associated to the current loyalty program.
currentSlab	string	Current tier of the customer in the loyalty program.
nextSlab	string	Next loyalty tier of the customer.
nextSlabSerialNumber	int	Serial number of the next tier. Lowest tier will have 1, succeeding tier will have 2 and so on.
nextSlabDescription	string	Description of the next tier as saved in the loyalty program.
slabSNo	int	Serial number of the current tier of the customer. Lowest tier will have 1, succeeding tier will have 2 and so on.
slabExpiryDate	date-time	Expiry date of the current loyalty tier of the customer in `YYYY-MM-DD HH:MM:SS`.
registered_on	date-time	Date on which the customer is enrolled in the org's loyalty.
updated_on	date-time	Recent date on which the customer details are updated.
type	enum	Loyalty 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.
sideEffects	Object	Object containing side effects (additional information) for the customer creation, if any.
entityType	Enum	Entity which receives points. Possible values: `USER`, `USERGROUP2`, `GROUP2`
rawAwardedPoints	BigDecimal	Total number of points awarded without any rounding applied.
customerId	Integer	Unique ID of the customer who is awarded points
awardedPoints	BigDecimal	Total number of points awarded with rounding applied.
type	Enum	Type of award rewarded to the customer.
isReferrer	Boolean	Indicates if the customer is a referrer. `true`: Customer is the referrer. `false`: Customer is not the referrer. This field is visible when a referrer (customer who is referring another customer) is awarded an incentives.
custom_fields	obj	Transaction or line-item level custom field details - field name (`name`) and field value (`value`).
extended_fields	obj	Transaction or line-item level extended field details - extended field name (`name`) and extended field value (`value`).

{
  "response": {
    "status": {
      "success": "true",
      "code": 200,
      "message": "Success"
    },
    "transactions": {
      "transaction": [
        {
          "id": 884656083,
          "shipping_source_till_code": "",
          "number": "test00transact071",
          "bill_client_id": "",
          "type": "REGULAR",
          "delivery_status": "DELIVERED",
          "parent_bill_number": "",
          "outlier_status": "NORMAL",
          "customer": {
            "user_id": "564703252",
            "mobile": "919999988886",
            "firstname": "Tjuser",
            "lastname": "eightysix",
            "email": "[email protected]",
            "external_id": "0000011110",
            "lifetime_points": "23002",
            "loyalty_points": "2",
            "current_slab": "Ruby",
            "tier_expiry_date": "2125-02-10 23:59:59",
            "points_summaries": {
              "points_summary": [
                {
                  "programId": "973",
                  "redeemed": "0",
                  "expired": "23000",
                  "returned": "0",
                  "adjusted": "0",
                  "lifetimePoints": "23000",
                  "loyaltyPoints": "0",
                  "cumulativePurchases": "142000",
                  "currentSlab": "Ruby",
                  "nextSlab": "Emerald",
                  "nextSlabSerialNumber": "6",
                  "nextSlabDescription": "Tier 6",
                  "slabSNo": "5",
                  "slabExpiryDate": "2125-02-10 23:59:59",
                  "totalPoints": ""
                },
                {
                  "programId": "983",
                  "redeemed": "0",
                  "expired": "0",
                  "returned": "0",
                  "adjusted": "0",
                  "lifetimePoints": "2",
                  "loyaltyPoints": "2",
                  "cumulativePurchases": "154000",
                  "currentSlab": "Coral",
                  "nextSlab": "Opal",
                  "nextSlabSerialNumber": "3",
                  "nextSlabDescription": "Tier 3",
                  "slabSNo": "2",
                  "slabExpiryDate": "2125-01-20 23:59:59",
                  "totalPoints": ""
                }
              ]
            },
            "lifetime_purchases": "142000",
            "type": "LOYALTY",
            "source": "instore"
          },
          "side_effects": {
            "effect": [
              {
                "awarded_points": 100,
                "total_points": 100,
                "customer_id": "424133043",
                "type": "points"
              },
              {
                "awarded_points": 100,
                "customer_id": "424133021",
                "is_referrer": "true",
                "type": "points"
              }
            ]
          },
          "source": "INSTORE",
          "item_status": {
            "success": "true",
            "code": 600,
            "message": "Transaction added successfully"
          }
        }
      ]
    }
  }
}

{
  "response": {
    "status": {
      "success": "true",
      "code": 200,
      "message": "Success"
    },
    "transactions": {
      "transaction": [
        {
          "id": 37813251,
          "shipping_source_till_code": "",
          "number": "BILL99",
          "bill_client_id": "",
          "type": "REGULAR",
          "delivery_status": "DELIVERED",
          "parent_bill_number": "",
          "outlier_status": "NORMAL",
          "customer": {
            "user_id": "342963216",
            "mobile": "919999000001",
            "firstname": "Tom",
            "lastname": "Sawyer",
            "email": "",
            "external_id": "",
            "lifetime_points": "106",
            "loyalty_points": "106",
            "current_slab": "bronze",
            "tier_expiry_date": "2119-09-20 23:59:59",
            "points_summaries": {
              "points_summary": [
                {
                  "programId": "1016",
                  "redeemed": "0",
                  "expired": "0",
                  "returned": "0",
                  "adjusted": "0",
                  "lifetimePoints": "106",
                  "loyaltyPoints": "106",
                  "cumulativePurchases": "18000",
                  "currentSlab": "bronze",
                  "nextSlab": "silver",
                  "nextSlabSerialNumber": "2",
                  "nextSlabDescription": "silver",
                  "slabSNo": "1",
                  "slabExpiryDate": "2119-09-20 23:59:59",
                  "totalPoints": ""
                }
              ]
            },
            "lifetime_purchases": "18000",
            "type": "LOYALTY",
            "source": "instore"
          },
          "side_effects": {
            "effect": [
              {
                "alternate_currency_identifier": "rgpws7",
                "alternate_currency_name": "ac1",
                "awarded_value": "110",
                "type": "alternate_currency"
              },
              {
                "alternate_currency_identifier": "pJ6E8A",
                "alternate_currency_name": "ac2",
                "awarded_value": "500",
                "type": "alternate_currency"
              },
              {
                "awarded_points": "120",
                "total_points": "2161",
                "type": "points"
              },
              {
                "previous_slab_name": "alpha1",
                "previous_slab_number": "1",
                "upgraded_slab_name": "Beta1",
                "upgraded_slab_number": "2",
                "type": "slab"
              }
            ]
          },
          "source": "ECOMM",
          "item_status": {
            "success": "true",
            "code": 600,
            "message": "Transaction added successfully"
          }
        }
      ]
    }
  }
}

Language

Credentials

Basic

base64

URL

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