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

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 in InTouch Settings > System & Deployment > InTouch POS Configuration > Billing. Note: The maximum length for a bill number is 50 characters.
amountdoubleNet 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
discountdoubleDiscount availed for the transaction or line item (discount amount).
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. 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.
ratefloatPrice of each line-item.
valuedoubleRepresents 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_timedate-timeDate and time of the transaction. By default, the current system date and time will be considered.
gross_amountdoubleRepresents 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_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.

{
  "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"
          }
        }
      ]
    }
  }
}
📘

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

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 Body

{
  "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"
          }
        }
      ]
    }
  }
}

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

Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!