post https://{host}/v2/transactions
Lets you add a new transaction or return an existing transaction. It supports both loyalty and not-interested transactions.
Rate Limit
| Region | Default Limit (RPM) |
|---|---|
| Asia-2 (Singapore) | 1500 |
| Asia-1 (N. Virginia) | 1500 |
| EMEA (Ireland) | 700 |
Note
- To avoid misunderstandings arising from timezone conversion, you can raise a ticket and enable the
CONF_ORG_DISABLE_MACHINE_TIME_CONVconfiguration. When the configuration is enabled, the time from the payload, without the UTC offset, is stored in the database for all clusters. For more information, refer to the documentation here.
Request Query Parameters
| Parameter | Type | Description |
|---|---|---|
| identifierName* | Enum | Pass any of the registered identifier name of the customer. Values: mobile, email, externalId, id, wechat, martjackId, fbId (Facebook ID), cardnumber, cardExternalId. |
| identifierValue* | string | Pass the respective identifier value. For example if identifierType is mobile, identifierValue is mobile number. |
| source | Enum | Pass the 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). |
| accountId | string | For sources with multiple accounts (such as MARTJACK, WECHAT), pass the respective account ID. Not applicable for INSTORE source. |
| use_asynch | boolean | Pass true to run Loyalty activities in the background, side effects will not be returned in the API response. If false, API will wait for Loyalty activities to complete and then respond to the client with side effects in the API response. |
| rawSideEffects | boolean | Pass true to get complete details of incentives such as awardOn, expiryDate, strategyIds and so on. |
Request Body Parameters
| Parameter | Type | Description |
|---|---|---|
| extendedFields | obj | Valid transaction level extended field details in name and value pairs. |
| type* | Enum | Type of transaction. Supported value: REGULAR for loyalty transactions. RETURN for return transactions. NOT_INTERESTED, NOT_INTERESTED_RETURN. |
| returnType** | Enum | For a return transaction, pass the return type. Value: AMOUNT, FULL, LINE_ITEM, CANCELLED. |
| notInterestedReason | string | Notes on why the customer is not interested to enroll into the loyalty (type = NOT_INTERESTED). Max characters supported - 255. |
| billNumber* | string | Unique transaction number for normal or mixed transactions and original transaction number for return transactions. Note: The maximum length for a bill number is 50 characters. |
| id | long | Transaction ID of the transaction that needs to be returned. Identifies the specific transaction to be returned when identical bill numbers exist across different transactions. This is applicable when the CONF_LOYALTY_BILL_NUMBER_UNIQUE_ONLY_STORE configuration is enabled, and the same bill number is used for transactions at different stores. Example: Store A: Customer transaction with bill number B1 Store B: Different transaction also with bill number B1 In this scenario, you can include the transaction ID in the return transaction payload to: - Distinguish between transactions with identical bill numbers - Prevent failures in return transactions due to duplicate bill numbers |
| billAmount | double | Net transaction amount. |
| billingDate | date-time | Date and time of the transaction in the ISO 8601 format - YYYY-MM-DDTHH:MM:SSZ. |
| discount | double | Discount availed for the transaction or line item (discount amount). |
| grossAmount | double | Transaction amount before discount. |
| outlierStatus | Enum | Transaction level outlier status. Values: NORMAL, INTERNAL, FRAUD, OUTLIER, TEST, DELETED, FAILED, OTHER. This overrides the outlier status of the configured outlier settings. |
| note | string | Additional information about the transaction. |
| deliveryStatus | Enum | Delivery status of the item. Values: PLACED, PROCESSED, SHIPPED, DELIVERED, RETURNED.You can update the status using v2 PUT /transactions |
| userGroup2Id | int | External ID of the user group to be associated with the transaction. Any one among the parameters with userGroup2 is required to associate the transaction with a group. |
| userGroup2PrimaryUserId | long | ID of the primary user of the group to be associated with the transaction. |
| userGroup2ExternalId | string | External ID of the user group to be associated with the transaction. |
| currencyCode | string | ISO currency code of the transaction to add transaction with local currency. For example, INR for Indian Rupee, SGD for Singapore Dollar, EUR for Euro, IQD for Iraqi Dinar. Pass the currency code that are supported for your org (InTouch > Organization Setup) and ensure the currency conversion ratio is set using v2/currencyratio. |
| addWithLocalCurrency | boolean | Pass true to add a transaction in local currency. |
| customFields | obj | Details of transaction level or transaction line-item level custom fields. |
| purchaseTime | date-time | Actual date of transaction of the returning bill in Date and time of the transaction in ISO 8601 standard - YYYY-MM-DDTHH:MM:SSZ. |
| promotionEvaluationId | string | Promotion evaluation code (cart/catalog) applied for the transaction. |
| appliedPromotionIdentifiers | array | Base 64 encoded string of Cart/catalog promotion identifiers that are applied to the transaction. It will have the details mentioned here {"promotionId":"612e5c5e4133b56abe0f073e","discount":"1000.000000","amount":"3000.000000","discountAppliedQty":"1","promotionAppliedQty":"3.000000","redemptionCount":1,"sku":"JNSREG02","version":"v1"} |
| loyaltyPromotionIdentifiers | array | Identifier(s) of loyalty promotion(s) that you want to tag to the transaction. |
| lineitemsV2 | obj | Details of line items. |
| attribution | obj | Mapping to tag the transaction to a different user or till (other than the current user). |
| redemptions | obj | Details of points and coupon redemptions for the transaction. |
| paymentModes | obj | Payment details used for the transaction. |
lineitemsV2 Object
| Parameter | Type | Description |
|---|---|---|
| amount | double | Net line item amount. Value - discount = amount. |
| description | string | One or two liner description of the line-item. |
| discount | int | Discount received on the line item. |
| itemCode | string | Unique code of the transaction line-item. |
| qty | double | Quantity of the current line item. |
| rate | double | Price of each line item. |
| serial | string | Serial number of the line-item. |
| value | double | Gross amount of the item. Usually, rate*qty = value. |
| returnable | boolean | Pass true if the item can be returned post purchase. |
| reutrnableDays | int | Maximum number of days the item is allowed to return. |
| customFields | obj | Transaction or line-item level custom field details. |
| imgUrl | string | URL of the product image. |
| attributes | obj | Attributes of the product in name-value pairs. |
| addOnDetails | obj | Details add-on item. |
| splitDetails | obj | Details of split item. |
| parentBillNumber | string | Return transaction number. Applicable only for mixed transaction (transaction that involves both purchase and return - exchange). |
| purchaseTime | date-time | Actual date of transaction of the return item in ISO 8601 format - YYYY-MM-DDTTHHSSZ. |
| returnType | Enum | Return type of the line item. Value - AMOUNT, FULL, LINE_ITEM. |
| type | Enum | Type of the line item. Value: REGULAR (for regular line item purchase), NOT_INTERESTED (for line item purchase with no customer tagging), RETURN (to return a regular line item ), NOT_INTERESTED_RETURN (to return a line item of no-interested transaction). |
| appliedPromotionIdentifiers | array | Cart or catalog promotions applied to the transaction. |
| extendedFields | obj | Valid transaction line-item level extended field details. |
| comboDetails | obj | Details combo, bundle, or split items. |
comboDetails object
| Parameter | Type | Description |
|---|---|---|
| itemCode | string | Unique line-item code. |
| quantity | double | Quantity of the current combo item. |
| description | string | One or two liner description of add-on, split, or combo item. |
| rate | double | Price of the combo item. |
| value | double | Item price excluding discount. |
| comboType | string | Type of the combo. COMBO_PARENT, COMBO_ITEM, ADD_ON_ITEM, SPLIT. |
attribution Object
| Parameter | Type | Description |
|---|---|---|
| createDate | date-time | Date of the transaction in ISO 8601 standard format. |
| createdBy | obj | User ID or store entity (like TILL ID, store ID) associated with the transaction. |
| code | string | Unique code of the entity. |
| type | Enum | Type of the attribution entity. Value: ZONE, CONCEPT, STORE, TILL, STR_SERVER, ADMIN_USER, ASSOCIATE, RULE, OU. |
redemptions Object
| Parameter | Type | Description |
|---|---|---|
| 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, [727272, 237878] |
paymentModes Object
| Parameter | Type | Description |
|---|---|---|
| mode | string | Mode of payment. |
| value | double | Amount paid through the current mode. |
| notes | string | Additional information related to the payment mode. Max characters - 250. |
| attributes | obj | Attributes of the payment mode as name-value pairs. |
Error codes
| Error code | Cause | Solution |
|---|---|---|
| Time mismatch between billing time and response time | Time conversion is not disabled. | Enable the CONF_ORG_DISABLE_MACHINE_TIME_CONV configuration. When the configuration is enabled, the time from the payload, without the UTC offset, is stored in the database for all clusters. For more information, refer to the documentation here. |
| 624: Invalid return transaction time, Return transaction should happen after add transaction | Incomplete body parameters | Parameter purchaseTime should be passed in the body. |
| 603: Invalid transaction id | Transaction ID is incorrect | Use the correct transaction ID. |