post
https://{host}/v1.1/transaction/add
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
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.
[!NOTE]
The precision of monetary fields (amount, rate, value, discount) in transactions and line items is controlled by the AMOUNT_ROUNDING_OFF_TO_DECIMAL_PLACES configuration. If this configuration is set to a value greater than or equal to 0, all monetary fields are rounded down (using Math.floor) to the specified number of decimal places. For example, a value of 38.98 may be rounded to 38.97. To ensure correct storage and retrieval of decimal values, set AMOUNT_ROUNDING_OFF_TO_DECIMAL_PLACES to one more than the value of CONF_DECIMAL_PLACES_FOR_BASE_CURRENCY (for example, if CONF_DECIMAL_PLACES_FOR_BASE_CURRENCY is 2, set AMOUNT_ROUNDING_OFF_TO_DECIMAL_PLACES to 3).
[!IMPORTANT]
A successful API response (status code 200) only confirms that the transaction was created. Points accrual and promotion triggering depend on active loyalty program rules, store attribution (using the X-CAP-API-ATTRIBUTION-ENTITY-CODE header), product eligibility, and customer tier. If no rules match, the transaction may not reflect points or rewards in Member Care. Always review your loyalty program rules and product eligibility to ensure expected outcomes.
[!CAUTION]
The transaction/add API processes one request per customer at a time. If two requests for the same customer are submitted simultaneously, one succeeds and the other is rejected with warning code 521 ("Multiple actions running for the same customer"). The retry mechanism is hardcoded and cannot be adjusted. To prevent this in bulk submission scenarios, send transactions for the same customer sequentially, not in parallel. If a 521 is returned, wait briefly and resubmit the failed transaction.
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_PROGRAMfor your org.
Redeeming cart promotions for transactions
To redeem a cart promotion for a transaction made using v1 transaction API, use the Redeem Cart Promotion API after you evaluate and add the transaction for a customer. To apply and redeem the cart promotion while making a transaction, use the Transaction V2 API. With this API, you can add a transaction, apply, and redeem a cart promotion in a single call.
Note
Negative values for the transaction values such as amount, discount will not be considered.
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. The value is rounded down to the number of decimal places set in the AMOUNT_ROUNDING_OFF_TO_DECIMAL_PLACES configuration, if enabled. |
| discount | double | Discount availed for the transaction or line item (discount amount). The value is rounded down to the number of decimal places set in the AMOUNT_ROUNDING_OFF_TO_DECIMAL_PLACES configuration, if enabled. |
| 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. The value is rounded down to the number of decimal places set in the AMOUNT_ROUNDING_OFF_TO_DECIMAL_PLACES configuration, if enabled. |
| value | double | Represents the pre-discount total for a single line item. Calculated as: value = rate × quantity. Example: If a line item has a rate of $10 and quantity of 2, value would be $20. The value is rounded down to the number of decimal places set in the AMOUNT_ROUNDING_OFF_TO_DECIMAL_PLACES configuration, if enabled. |
| 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. Line item level custom fields are not supported. |
| 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.
NoteFor 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 |
|---|---|---|
| Note: Monetary fields (amount, rate, value, discount) in return transactions and line items are rounded down to the number of decimal places set in the AMOUNT_ROUNDING_OFF_TO_DECIMAL_PLACES configuration, if enabled. Set this configuration to one more than CONF_DECIMAL_PLACES_FOR_BASE_CURRENCY to ensure correct storage and retrieval of decimal values. | ||
| 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 inYYYY-MM-DD format. |
| notes | string | Additional information about the transaction. |
| amount* | double | Amount that needs to be returned. The value is rounded down to the number of decimal places set in the AMOUNT_ROUNDING_OFF_TO_DECIMAL_PLACES configuration, if enabled. |
| qty* | int | Quantity of the current line-item. |
| rate | float | Price of each line-item. The value is rounded down to the number of decimal places set in the AMOUNT_ROUNDING_OFF_TO_DECIMAL_PLACES configuration, if enabled. |
| value | float | Gross transaction amount (transaction amount excluding discount). The value is rounded down to the number of decimal places set in the AMOUNT_ROUNDING_OFF_TO_DECIMAL_PLACES configuration, if enabled. |
| 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. The value is rounded down to the number of decimal places set in the AMOUNT_ROUNDING_OFF_TO_DECIMAL_PLACES configuration, if enabled. |
| 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. |
| Enum | Entity which receives points. Possible values: USER, USERGROUP2, GROUP2 |
| BigDecimal | Total number of points awarded without any rounding applied. |
| Integer | Unique ID of the customer who is awarded points |
| BigDecimal | Total number of points awarded with rounding applied. |
| Enum | Type of award rewarded to the customer. |
| 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"
}
}
]
}
}
}