Add Transaction API

Use this API to add a customer transaction to the loyalty system. Supports regular purchases, returns, and not-interested transactions.

Example request

curl --location 'https://eu.api.capillarytech.com/v2/transactions/bulk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VjMT' \
--data '[
    {
        "identifierType": "mobile",
        "identifierValue": "919999988886",
        "source": "INSTORE",
        "accountId": "",
        "type": "REGULAR",
        "billNumber": "test00transact087",
        "billingDate": "2025-04-11T11:00:00+05:30",
        "discount": "",
        "billAmount": "6000.0",
        "note": "Transaction number 87",
        "grossAmount": "110",
        "deliveryStatus": "PLACED",
        "paymentModes": [
            {
                "mode": "CardPayment",
                "value": "6000.0",
                "notes": "SPay",
                "attributes": {
                    "card_type": "Visa"
                }
            }
        ],
        "lineItemsV2": [
            {
                "itemCode": "model_id_001",
                "amount": 2000.0,
                "description": "Steel Bottle",
                "discount": 0,
                "rate": 500.0,
                "qty": 4,
                "value": 2000.0,
                "extendedFields": {
                    "MetalRate": "22.02",
                    "GrossWeight": "10.50"
                }
            },
            {
                "itemCode": "model_id_002",
                "amount": 2000.0,
                "description": "Sports Shoe",
                "discount": 0,
                "rate": 1000.0,
                "value": 2000.0,
                "qty": 2,
                "extendedFields": {
                    "MetalRate": "22.02",
                    "GrossWeight": "10.50"
                }
            },
            {
                "itemCode": "model_id_003",
                "amount": 2000.0,
                "rate": 2000.0,
                "qty": 1,
                "value": 2000.0,
                "extendedFields": {
                    "gender": "Male",
                    "marital_status": "Married"
                },
                "customFields": {
                    "cashierid": "jim2345",
                    "city": "Bangalore"
                }
            } 
        ]
    },
    {
        "identifierType": "mobile",
        "identifierValue": "919999988886",
        "source": "INSTORE",
        "accountId": "",
        "type": "REGULAR",
        "billNumber": "test00transact086",
        "billingDate": "2025-04-11T11:00:00+05:30",
        "discount": "1000",
        "billAmount": "6000.0",
        "note": "Transaction number 86",
        "grossAmount": "7000",
        "deliveryStatus": "PLACED",
        "paymentModes": [
            {
                "mode": "CardPayment",
                "value": "6000.0",
                "notes": "SPay",
                "attributes": {
                    "card_type": "Visa"
                }
            }
        ],
        "lineItemsV2": [
            {
                "itemCode": "model_id_001",
                "amount": 2000.0,
                "description": "Steel Bottle",
                "discount": 1000.0,
                "rate": 750.0,
                "qty": 4,
                "value": 3000.0,
                "extendedFields": {
                    "MetalRate": "22.02",
                    "GrossWeight": "10.50"
                }
            },
            {
                "itemCode": "model_id_002",
                "amount": 2000.0,
                "description": "Sports Shoe",
                "discount": 0,
                "rate": 1000.0,
                "value": 2000.0,
                "qty": 2,
                "extendedFields": {
                    "MetalRate": "22.02",
                    "GrossWeight": "10.50"
                }
            },
            {
                "itemCode": "model_id_003",
                "amount": 2000.0,
                "rate": 2000.0,
                "qty": 1,
                "value": 2000.0,
                "extendedFields": {
                    "gender": "Male",
                    "marital_status": "Married"
                },
                "customFields": {
                    "cashierid": "jim2345",
                    "city": "Bangalore"
                }
            }    
        ]
    }
]'

Prerequisites

Authentication details
Authorization/access group details

🚧
You cannot register a customer with this API. Pass only registered customer identifiers.

Header information

Header name	Description
SKIP-DOWNSTREAM	When set to `true`, the transaction is written directly to the database without notifying downstream systems (Loyalty Engine/EMF or event notification services). No loyalty actions or event triggers are executed. Use this to import transaction data without generating side effects.

Path parameters

Not applicable.

Query parameters

Not applicable.

Body parameters

Transaction (top level)

Field	Type	Required	Description
identifierType	enum	Yes	Registered identifier type of the customer. Values: `mobile`, `email`, `externalId`, `wechat`, `martjackId`, `fbId`, `id`.
identifierValue	string	Yes	Value for the specified `identifierType`. For example, if `identifierType` is `mobile`, pass the mobile number.
source	enum	Yes	Source from which the transaction originates. Values: `INSTORE`, `WECHAT`, `MARTJACK`, `WEB_ENGAGE`, `ECOMMERCE`, `JD`, `TAOBAO`, `TMALL`, `FACEBOOK`, `WEBSITE`, `OTHERS`.
accountId	string	Optional	For multi-account sources such as `MARTJACK` and `WECHAT`, pass the respective account ID.
type	enum	Yes	Transaction type. Values: `REGULAR`, `RETURN`, `NOT_INTERESTED`, `NOT_INTERESTED_RETURN`.
notInterestedReason	string	Optional	Reason the customer declined loyalty enrollment. Applicable when `type` is `NOT_INTERESTED`. Max 255 characters.
returnType	enum	Conditional	Return type. Required when `type` is `RETURN`. Values: `AMOUNT`, `FULL`, `LINE_ITEM`, `CANCELLED`.
billNumber	string	Yes	Unique transaction number. For return transactions, pass the original transaction's bill number. Max 50 characters. Uniqueness scope (till, store, or org) is org-configured.
id	long	Optional	Transaction ID of the transaction to return. Use when `CONF_LOYALTY_BILL_NUMBER_UNIQUE_ONLY_STORE` is enabled and the same bill number exists across multiple stores, to identify which specific transaction to return.
billAmount	double	Yes	Net transaction amount. Negative values are not accepted.
billingDate	date-time	Optional	Date and time of the transaction. ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
discount	double	Optional	Discount amount applied at the transaction level. Negative values are not accepted.
grossAmount	double	Optional	Transaction amount before discount.
outlierStatus	enum	Optional	Transaction-level outlier status. Overrides configured outlier settings. Values: `NORMAL`, `INTERNAL`, `FRAUD`, `OUTLIER`, `TEST`, `DELETED`, `FAILED`, `OTHER`.
note	string	Optional	Additional information about the transaction.
deliveryStatus	enum	Optional	Delivery status of the item. Values: `PLACED`, `PROCESSED`, `SHIPPED`, `DELIVERED`, `RETURNED`. Update this field using `v2/transaction/update`.
purchaseTime	date-time	Conditional	Billing time of the original transaction for which a return is being made. Required when `type` is `RETURN`. ISO 8601: `YYYY-MM-DDTHH:MM:SSZ`.
currencyCode	string	Optional	ISO currency code for transactions in local currency. Examples: `INR`, `SGD`, `EUR`, `IQD`. The currency must be enabled in InTouch > Organization Setup and a conversion ratio must be set via `v2/currencyratio`.
addWithLocalCurrency	boolean	Optional	Pass `true` to add the transaction in local currency.
promotionEvaluationId	string	Optional	Promotion evaluation code (cart or catalog) applied to the transaction.
appliedPromotionIdentifiers	array	Optional	Base64-encoded cart or catalog promotion identifiers applied to the transaction. Each entry contains: `promotionId`, `discount`, `amount`, `discountAppliedQty`, `promotionAppliedQty`, `redemptionCount`, `sku`, `version`.
loyaltyPromotionIdentifiers	array	Optional	Identifiers of loyalty promotions to tag to the transaction.
extendedFields	object	Optional	Transaction-level extended field details as name-value pairs.
lineItemsV2	object	Optional	Line item details. See lineItemsV2 object.
attribution	object	Optional	Maps the transaction to a different user or till. See attribution object.
redemptions	object	Optional	Points and coupon redemption details. See redemptions object.
paymentModes	object	Optional	Payment mode details. See paymentModes object.

User group parameters

Use these parameters to associate the transaction with a user group. At least one userGroup2 parameter is required to make the association.

Field	Type	Required	Description
userGroup2Id	int	Conditional	Unique ID of the user group.
userGroup2PrimaryUserId	long	Conditional	User ID of the primary group member.
userGroup2ExternalId	string	Conditional	External ID of the user group.
userGroup2PrimaryUserIdentifierType	enum	Conditional	Identifier type for the group primary member. Values: `mobile`, `email`, `externalId`, `wechat`, `martjackId`, `fbId`, `id`.
userGroup2PrimaryUserIdentifierValue	string	Conditional	Value for the specified group identifier type.
userGroup2PrimaryUserSource	enum	Conditional	Source in which the group primary member's identifier is registered. Values: `INSTORE`, `WECHAT`, `MARTJACK`, `WEB_ENGAGE`, `ECOMMERCE`, `JD`, `TAOBAO`, `TMALL`, `FACEBOOK`, `WEBSITE`, `OTHERS`.
userGroup2PrimaryUserAccountId	string	Conditional	Account ID for multi-account sources such as `WECHAT`.

`attribution` object

Field	Type	Required	Description
createDate	date-time	Optional	Date of the transaction. ISO 8601 format.
createdBy	object	Optional	User ID or store entity (till, store) to associate with the transaction.
createdBy.code	string	Optional	Unique code of the entity.
createdBy.type	enum	Optional	Type of the attribution entity. Values: `ZONE`, `CONCEPT`, `STORE`, `TILL`, `STR_SERVER`, `ADMIN_USER`, `ASSOCIATE`, `RULE`, `OU`.

`lineItemsV2` object

📘
Note
Custom fields are supported only at the customer, bill, and redemption levels. Only extended fields are supported at the line item level.

Field	Type	Required	Description
amount	double	Optional	Net line item amount (`value` minus `discount`).
description	string	Optional	Short description of the line item.
discount	int	Optional	Discount applied to the line item.
itemCode	string	Optional	Unique code of the line item.
qty	double	Optional	Quantity of the line item.
rate	double	Optional	Price per unit.
serial	string	Optional	Serial number of the line item.
value	double	Optional	Gross amount of the line item (`rate` multiplied by `qty`).
returnable	boolean	Optional	Pass `true` if the item is eligible for return.
returnableDays	int	Optional	Maximum number of days within which the item can be returned.
customFields	object	Optional	Transaction or line item-level custom field details.
imgUrl	string	Optional	URL of the product image.
attributes	object	Optional	Attributes of combo, bundle, or split items.
comboDetails	object	Optional	Details of combo or bundle items.
addOnDetails	object	Optional	Details of add-on items.
splitDetails	object	Optional	Details of split items.
parentBillNumber	string	Optional	Original transaction bill number for return line items in a mixed transaction (one that contains both purchase and return items).
purchaseTime	date-time	Conditional	Billing time of the original transaction for which a return is being made. Required for return line items. ISO 8601: `YYYY-MM-DDTHH:MM:SSZ`.
returnType	enum	Optional	Return type for the line item. Values: `AMOUNT`, `FULL`, `LINE_ITEM`. Not applicable when the transaction-level `returnType` is `FULL` or `AMOUNT`.
type	enum	Optional	Type of the line item. Values: `REGULAR`, `NOT_INTERESTED`, `RETURN`, `NOT_INTERESTED_RETURN`.
appliedPromotionIdentifiers	array	Optional	Base64-encoded cart or catalog promotions applied to the line item. Same structure as the transaction-level `appliedPromotionIdentifiers`.
extendedFields	object	Optional	Line item-level extended field details.

`redemptions` object

Field	Type	Required	Description
pointsRedemptions	array	Optional	Unique points redemption IDs to apply to the transaction. Example: `[727272, 237878]`.
couponRedemptions	array	Optional	Unique coupon redemption IDs to apply to the transaction. Example: `[727272, 237878]`.

`paymentModes` object

Field	Type	Required	Description
mode	string	Optional	Payment mode.
value	double	Optional	Amount paid via this mode.
notes	string	Optional	Additional payment mode information. Max 250 characters.
attributes	object	Optional	Payment mode attributes as name-value pairs.

Example response

{
    "response": [
        {
            "entityId": 884796252,
            "result": {
                "identifierType": "mobile",
                "identifierValue": "919999988886",
                "source": "INSTORE",
                "accountId": "",
                "deliveryStatus": "PLACED",
                "type": "REGULAR",
                "billAmount": 6000.0,
                "billNumber": "test00transact087",
                "grossAmount": 110.0,
                "note": "Transaction number 87",
                "lineItemsV2": [
                    {
                        "amount": 2000.0,
                        "description": "Steel Bottle",
                        "discount": 0.0,
                        "itemCode": "model_id_001",
                        "qty": 4.0,
                        "rate": 500.0,
                        "value": 2000.0,
                        "returnable": true,
                        "returnableDays": -1,
                        "comboDetails": [],
                        "addOnDetails": [],
                        "splitDetails": [],
                        "extendedFields": {
                            "GrossWeight": 10.5,
                            "MetalRate": 22.02
                        }
                    },
                    {
                        "amount": 2000.0,
                        "description": "Sports Shoe",
                        "discount": 0.0,
                        "itemCode": "model_id_002",
                        "qty": 2.0,
                        "rate": 1000.0,
                        "value": 2000.0,
                        "returnable": true,
                        "returnableDays": -1,
                        "comboDetails": [],
                        "addOnDetails": [],
                        "splitDetails": [],
                        "extendedFields": {
                            "GrossWeight": 10.5,
                            "MetalRate": 22.02
                        }
                    },
                    {
                        "amount": 2000.0,
                        "itemCode": "model_id_003",
                        "qty": 1.0,
                        "rate": 2000.0,
                        "value": 2000.0,
                        "returnable": true,
                        "returnableDays": -1,
                        "customFields": {
                            "cashierid": "jim2345",
                            "city": "Bangalore"
                        },
                        "comboDetails": [],
                        "addOnDetails": [],
                        "splitDetails": [],
                        "extendedFields": {}
                    }
                ],
                "notInterestedReason": "",
                "sideEffects": [
                    {
                        "entityType": "USER",
                        "rawAwardedPoints": 1.000,
                        "customerId": 564703252,
                        "awardedPoints": 1,
                        "type": "points"
                    }
                ],
                "isUseDefaultUserGroup2": false,
                "paymentModes": [
                    {
                        "mode": "CardPayment",
                        "value": 6000.0,
                        "notes": "SPay",
                        "attributes": {
                            "card_type": "Visa"
                        }
                    }
                ],
                "billingDate": "2025-04-11T05:30:00Z",
                "useDefaultUserGroup2": false
            },
            "errors": [],
            "warnings": [
                {
                    "status": false,
                    "code": 91016,
                    "message": "Extended field name gender is invalid."
                },
                {
                    "status": false,
                    "code": 91016,
                    "message": "Extended field name marital_status is invalid."
                }
            ],
            "loyaltyDetails": []
        },
        {
            "entityId": 884796253,
            "result": {
                "identifierType": "mobile",
                "identifierValue": "919999988886",
                "source": "INSTORE",
                "accountId": "",
                "deliveryStatus": "PLACED",
                "type": "REGULAR",
                "billAmount": 6000.0,
                "billNumber": "test00transact086",
                "discount": 1000.0,
                "grossAmount": 7000.0,
                "note": "Transaction number 86",
                "lineItemsV2": [
                    {
                        "amount": 2000.0,
                        "description": "Steel Bottle",
                        "discount": 1000.0,
                        "itemCode": "model_id_001",
                        "qty": 4.0,
                        "rate": 750.0,
                        "value": 3000.0,
                        "returnable": true,
                        "returnableDays": -1,
                        "comboDetails": [],
                        "addOnDetails": [],
                        "splitDetails": [],
                        "extendedFields": {
                            "GrossWeight": 10.5,
                            "MetalRate": 22.02
                        }
                    },
                    {
                        "amount": 2000.0,
                        "description": "Sports Shoe",
                        "discount": 0.0,
                        "itemCode": "model_id_002",
                        "qty": 2.0,
                        "rate": 1000.0,
                        "value": 2000.0,
                        "returnable": true,
                        "returnableDays": -1,
                        "comboDetails": [],
                        "addOnDetails": [],
                        "splitDetails": [],
                        "extendedFields": {
                            "GrossWeight": 10.5,
                            "MetalRate": 22.02
                        }
                    },
                    {
                        "amount": 2000.0,
                        "itemCode": "model_id_003",
                        "qty": 1.0,
                        "rate": 2000.0,
                        "value": 2000.0,
                        "returnable": true,
                        "returnableDays": -1,
                        "customFields": {
                            "cashierid": "jim2345",
                            "city": "Bangalore"
                        },
                        "comboDetails": [],
                        "addOnDetails": [],
                        "splitDetails": [],
                        "extendedFields": {}
                    }
                ],
                "notInterestedReason": "",
                "sideEffects": [],
                "isUseDefaultUserGroup2": false,
                "paymentModes": [
                    {
                        "mode": "CardPayment",
                        "value": 6000.0,
                        "notes": "SPay",
                        "attributes": {
                            "card_type": "Visa"
                        }
                    }
                ],
                "billingDate": "2025-04-11T05:30:00Z",
                "useDefaultUserGroup2": false
            },
            "errors": [],
            "warnings": [
                {
                    "status": false,
                    "code": 91016,
                    "message": "Extended field name gender is invalid."
                },
                {
                    "status": false,
                    "code": 91016,
                    "message": "Extended field name marital_status is invalid."
                }
            ],
            "loyaltyDetails": []
        }
    ],
    "totalCount": 2,
    "failureCount": 0
}

Error and warning codes

Code	Type	Description
Time mismatch between billing time and response time	Error	Timezone conversion is not disabled. Enable `CONF_ORG_DISABLE_MACHINE_TIME_CONV` to store the time from the payload without UTC offset conversion. See Timezone Management.
624	Error	Invalid return transaction time. Return transaction should happen after add transaction. Include `purchaseTime` in the request payload.

Configurations

To enable or disable any of the following configurations, raise a Jira ticket to the Capillary Product Support team.

Configuration	Default	Description
CONF_ORG_DISABLE_MACHINE_TIME_CONV	Disabled	When enabled, stores the time from the payload without UTC offset conversion, for all clusters. See Timezone Management.
CONF_ALLOW_TRANSACTION_RETURN_AFTER_GROUP_TRANSITION	Disabled	When enabled, allows returns for former group members. When a return is performed for a user who has left the group, points allocated to the group as part of the original transaction are also reverted.
CONF_POINTS_RETURN_ENABLED	Enabled	When disabled, earned points are not reversed when a transaction is returned. To reverse points manually, use the Manual Points Adjustment API.
CONF_LOYALTY_BILL_NUMBER_UNIQUE_ONLY_STORE	Disabled	When enabled, bill number uniqueness is scoped to the store level. Use the `id` parameter in return transactions to disambiguate identical bill numbers across stores.
CONFIG_SKIP_SECONDARY_ID_ON_PRIMARY_MISMATCH	Disabled	When enabled, if the primary identifier differs but a secondary identifier matches, a new customer is registered with the primary identifier, ignoring the secondary. Configurable at InTouch > Organization Settings > Miscellaneous > Registration Page.