Transaction Rule Engine
Contents
Objective
- This module allows the Venture to set up flexible transactions to be applied based on events, conditions, triggers, and rules.
- The long-term goal is to have all transactions (fees, commissions, cancellations, tier, etc.) in one centralized module and to be able to apply rules with a high-level of granularity.
- Currently, fees and commissions are built in Seller Center legacy code.
- Using the Transaction Rule Engine, transactions will be transparent to everyone and can be dynamically adapted and combined within a transaction rule.
Also, when you have already enabled transaction_rule_engine/enabled and would like to switch to the modified Transaction Rule Engine, please have the transaction_rule_engine_2_ui_only/enabled configuration parameter set in order to add new transaction rules. After you have finished creating rules, have transaction_rule_engine_2/enabled enabled.
Tab Overview
The Transaction Rule Engine can be found under Administration > Transaction Rule Management.
Transaction Rule Engine consists of Variable Overview and the Transaction Rules Overview:
-
Variable Overview and Transaction Rules Overview:
- Maintained by Seller Center.
- As a mid-term goal, this right will be able to transferred to an admin user on the Venture-side.
-
Variable values:
- Maintained by Venture (e.g., Account Manager).
-
Macros:
- Used only by Seller Center maintenance team in order to create additional context for new rules.
Variable Overview
In Variable Overview, a user can create a variable that can be used for multiple calculations.
- This gives the user the freedom to dynamically set values for commissions or fees on Seller-level.
- Moreover, this way, VAT and WHT rates can be created individually for each Venture or country and can be applied on Seller-level.
- As a result, VAT and WHT rate calculations can be shown in the account statement and do not need any manual adjustment with an external tool (e.g., Excel files, etc.).
When adding a variable to the Transaction Rule Engine, the following information is required:
- “Variable Name”: Variable should have a unique name. Please make sure that this variable can be used by several transaction rules. Therefore, make sure that you are able to identify the variable easily.
- “Label”: Generated automatically and used to fetch information with variable values.
- “Description”: A short explanation of the variable
- “Type”: Defines if a variable value should be generated as a number or as a percentage.
-
“Inheritance Type”: You can define on which level you would like to manage values.
- “Global”: One global value is applied.
- “Global + Seller”: You can set a global value and a Seller-specific value.
- “Category”: You can set global and Seller-specific values on category-level (same logic as the legacy way to set commissions on a category-level).
After defining all fields and clicking “Save Changes,” the variable will be saved and displayed in both Variable Overview and in variable values.
Transaction Rules Overview
In Transaction Rules Overview, you can create and search for transaction rules. By clicking on a rule name, you are able to see all of its details.
To enable or disable rules simultaneously, do the following:
- Click the “Enable” or “Disable” button. Status will change to “Ready to be enabled” or “Ready to be disabled”
- Click “Publish changes” button to save changes.
When adding a transaction rule, the following information is required:
-
“Rule Name”: Rule should have a unique name and be as specific as possible in order to simplify the search.
- Bad example: “Commissions” (too generic)
- Good example: “Commission for local Sellers for drop shipping orders”
- “Account Statement Group”: Linked to transaction type and will be shown in account statements. You can find a list with predefined account statement groups. If you wish to create a custom account statement group, please refer to the Account Statement Groups Overview.
- “Description”: A short explanation of the transaction rule
- “Outcome”: Defines which type of transaction should be generated. Please make sure that the outcome name is included in your account statement group.
- “Enable pre-calculation”: Defines whether or not to specify events for transaction pre-calculation.
- “Pre-calculated on”: Specifies the events that will trigger the pre-calculation.
- “Events”: It is possible to choose one or multiple events that the transaction should be triggered by.
- “Condition”: Defines restrictions that have to be fulfilled for the rule to be applied (e.g., FirstDayofMonth && item.ShippingTypeIsDropshipping).
- “Net Amount Formula”: Defines the calculation that will be generated with the transaction rule before taxes.
- “VAT Formula”: Calculates a VAT rate using the outcome from net amount formula amount (will be displayed in account statement).
- “WHT Formula”: Calculates a WHT rate using the outcome from net amount formula amount (will be displayed in account statement).
- “Add to the latest closed account statement”: The created transaction will be associated with the previously closed account statement and correct the payout (click the link to read more about the feature).
After defining all fields and clicking “Save Changes,” the transaction rule will be saved and propagated in Transaction Rule Overview.
Variable Values
In the “Variable Value” tab, you can see a list with variables and edit values by clicking “Edit.” Depending on the inheritance type, you can set values on global or Seller-level, as well as on category-level.
Macros
The following tab is only visible to Seller Center’s maintenance team in order to simplify the context/attribute creation process.
When adding a context/attribute, the following information is needed:
- “Label”: Define a label that will be shown as an option during transaction rule creation.
- “Type”: Defines a value of the expression.
- “Description”: A short explanation of created context
- “Event”: Multiple events can be shown where macro can be used.
- “Expression”: Code of the macro
Example Macros
Name & Description | Expression | (example) Order States | Type |
areAllItemsShippedOrinFinalState All items are shipped or in final state |
reduce( map( order_items, expr(“status in [‘shipped’, ‘delivered’, ‘canceled’, ‘failed’, ‘returned’]“) ), and, true ) |
canceled, delivered, failed , returend shipped | boolean |
orderValue Amount of money within one order |
reduce( map( filter( order_items, expr(“‘shipped’ in statusHistory”) ), expr(“unitPrice”)), sum, 0 ) |
canceled, delivered, failed , returend shipped | numbe |
itemIsTheFirstOfThePackage Item is first hitting the targeted status in the package |
item_orderItemId in map( map(order_packages, expr(“items[0]“)), expr(“orderItemId”) ) |
canceled, delivered | boolean |
Account Statement Groups Overview
In Account Statement Groups Overview, a user can create account statement groups that will be linked to one of the default transaction types.
- Account statement groups will allow Ventures to create transaction rules in combinations that were not possible before (e.g., two or more rules generating transactions with the same reference and transaction type).
The only constraint for duplication protection is set regarding the account statement group/reference combination: in no case will the rules generate two transactions for the same account statement group/reference pair.
When adding a new account statement group, the following information is needed:
- “Account Statement Group Name”: Define a custom account statement group name.
-
“Transaction Type”: Choose the transaction type from the default list.
- This will be displayed for the Seller in the overview and account statement.
-
“Outcome”: Transaction outcome (Credit / Debit), which gets applied to the Account Statement
- Will be applied for all rules, which use a certain account statement group
After defining all fields and clicking “Save Changes,” the account statement group will be saved and displayed in the list when creating a transaction rule.
Available Contexts and Attributes
The following context parameters are available within the Transaction Rule Engine:
- Item: access all item attributes (e.g., item.unit_price, item.shipmentType.isDropShipping, item.shipping_fee)
- Seller: access all Seller attributes (e.g., seller.id)
The input fields “Condition” and “Calculation” have auto complete suggestions to help the user easily set up the rule.
Matrix of Available Contexts and Attributes
- “Shipped”
- “Delivered”
- “Canceled”
- “Returned”
- “Failed”
- “Imported”
The following table lists contexts or attributes that are only available for a specific event.
The event for “Day of the month (product)” means that there is daily a check in place, to go through all product of a seller to calculate transactions. This is helpfull in case daily storage fees should be applied for fulfillment products.
Context | Attribute | Description | Applicable in the following events: |
Item | cancelationDate | Date of cancellation | “Canceled” |
cancelationReason |
Name of the reason applied for item cancellation Example: item.cancelationReason == ‘out_ofstock’ |
“Canceled” | |
cancelationSource |
Source detection regarding where cancellation has been triggered. Possible options: “internal” / “external” Example: item.cancelationSource == CancelationSource.Internal |
“Canceled” | |
creationDate | Date when order was created (in Seller Center, which means imported from OMS). Should be used in combination with cancelationDate to calculate difference of days. | all | |
commission | Commission applied on item-level based on category | all | |
customerShippingFee | Customer shipping fee on order item-level | all | |
extendedPromisedShippingTime | all | ||
isFreeShipping |
Indicator whether shipping costs need to be calculated or not. Example: item.isFreeShipping == false |
all | |
returnReason |
Reason supplied for item return. Example: item.returnReason: == ‘error-_wrong_product’ |
“returned” | |
revenue | Paid price or unit price, depending on Seller commission calculation basis | all | |
orderDate | Date of order creation (import to Seller Center) | all | |
paidPrice | Price per unit after deductions | all | |
paymentMethod | Payment method chosen by customer | all | |
promissedShippingTime | Promised time when the order will be shipped | all | |
shipmentType | Access shipping types validators | all | |
shipmentType.isCrossDocking | Whether the item has been shipped by the Seller to the Venture before final delivery to the customer | all | |
shipmentType.isDropshipping | Return true if item shipping type is “Drop Shipping”; otherwise, return false | all | |
shipmentType.isOwnWarehouse | Indicates whether the item has been shipped to the customer by the Venture using fulfillment stocks. | all | |
shipmentType.shippingProviderType | Choose the name of a specific shipping provider. | all | |
shippingDate | Date when package was shipped | all | |
shippingServiceCost | Numerical value for shipping service costs that is sent from OMS to Seller Center. Value is received from OMS when feature is enabled. | all | |
taxPercent | Percent of VAT + WHT from unit/paid price | all | |
trackingCode | tracking code of an order item | ||
unitPrice | Price per unit before deductions | all | |
volumetricSize |
Value of package size that is imported from OMS. Allowed values: “S”, “M”, “L”, “XL”, “OZ”(over size) Example: item.volumetricSize != VolumetricSize.XL (as XL any of the other options are possible) |
all | |
voucherAmount |
Voucher amount that has been applied to the sales order item. Value is received from OMS |
all | |
hasPromotionVoucher | Based on the voucher code this property is checking if the order item is related to a “Promotion Voucher” and will return true or false response | all | |
promotionVoucher.amountFundedBySeller |
In case the order item is linked to a Promotion Voucher, this property will calculate the amount of the voucher that should be paid by the seller based on the configured percentage distribution in the promotion setup. It is a total number and by default, it will return zero. |
all | |
promotionVoucher.amountFundedByVenture |
In case the order item is linked to a Promotion Voucher, this property will calculate the amount of the voucher that should be paid by the ventures based on the configured percentage distribution in the promotion setup. It is a total number and by default, it will return zero. |
all | |
Seller | contractType | Associated contract type associated with Seller | all |
creationDate | Date when a seller was registered in Seller Center | all | |
id | Seller identification based on short code | all | |
isActive | Indicates whether Seller account is active. | First day of the month, Day of the month (product)* | |
isVerified | Indicates whether Seller account is verified. | First day of the month, Day of the month (product)* | |
kpi.CancellationRate | Cancellation rate calculates the percentage of orders canceledby the seller | all | |
kpi.operationalScore | Operational Score which got configured for a seller within the seller settings. Score is provided by the Venture | ||
rating | Current Seller rating of the Seller. Value is between 0-5 | all | |
statistics.itemsSold | Sum of ([Order items amount created during the last x days] – [Order items created during last x days (amount configurable) that are now canceled]) | all | |
taxClass | Default taxation class on Seller-level | all | |
tier | Current tier of the seller | all | |
statistics.lastClosedAccountStatement.sales | Sales made within the previous account statement period. | Account Statement Closed | |
statistics.lastClosedAccountStatement.deliveryFailedRate | Percentage of the items in status “Failed Delivery” to all order items received within the previous account statement period. | Account Statement Closed | |
statistics.lastClosedAccountStatement.returnedRate | Percentage of the items that has been returned to all order items received within the previous account statement period. | Account Statement Closed | |
statistics.lastClosedAccountStatement.pendingToReadyToShipIn48hRate | Percentage of the items that has been shipped within 48h to all order items received within the previous account statement period. | Account Statement Closed | |
statistics.lastClosedAccountStatement.failedByCustomReasonsRate |
Percentage of the items that has been failed/cancelled for custom reasons to all order items received within the previous account statement period. Please provide IDs of failure reasons that you would like to be calculated in the configuration parameter “statistic / seller/items_failure_reasons” |
Account Statement Closed | |
statistics.lastClosedAccountStatement.commissionPaid | Sum of the commission that needs to be paid by the seller in the previous account statement period. | Account Statement Closed | |
Critical KnowledgeIf you want to use statistics context, please create a TMLSD ticket with a request to start gathering and saving the data to the database.
|
|||
verificationDate | Date when a Seller was initially approved/verified by an Admin. | all | |
Date | addBusinessDays |
Add (or subtracts) days from a date, skipping any holidays or weekends (which are configured for Seller) Example for checking that more than two business days have passed between the order date and the cancellation event: Date.resetTime(Date.addBusinessDays(item.creationDate, 2)) == Date.resetTime(item.cancelationDate) |
all, Inventory Status Update (product), Inventory Status Update (order item) |
resetTime | Resets the time values of a date so that date calculation starts at midnight. | all | |
Product | currentPrice | Current active product price (either price or sale price, depending on the sale price period of the sale price) | all |
isInSubsidyPlan | Check to determine whether a product is part of a subsidy plan or not in order to trigger the according rules | ||
primaryCategory | Product is placed within the configured primaryCategory(s). | all | |
price | Product price | all | |
sku | Only applies for certain / configured product (Seller) SKUs | all | |
specialPrice | Sale or special price of a product | all | |
stock | Amount of items available for a product | all | |
volumetricWeight | Volumetric weight of a consignment product, which is allocated in the Ventures warehouse | all | |
Vars | venture specific list of variables | All variables that are configured in Seller Center can be used | |
VolumneSize | Constants for various volumne sizes, e.g. S, M, L,XL, OZ | all | |
Inventory | status | Status of product in OMS inventory state machine | Inventory Status Update (product), Inventory Status Update (order item) |
uid | Unique identifier of single product in warehouse | Inventory Status Update (product), Inventory Status Update (order item) | |
Payment | isPayMeNow | The source of payment creation is defining if it was an advance payment desired by seller or an automatic one | Payment Paid |
There are two additional configuration, which need to be enabled, when the events for “Day of the month (product)” should be used.
Configuration “daily/day_passed_event/enabled”, this configuration executes the rule, but no transaction gets triggered.
Configuration “daily/day_passed_event/process_products/enabled”, this executes the rule and the according transactions get triggered.
Available Operators
The Transaction Rule Engine uses an ExpressionLanguage component that support expressions syntax:
Supported Literals
The component supports:
- Strings: single and double quotes (e.g., ‘hello’)
- Numbers (e.g., 103)
- Arrays: using JSON-like notation (e.g., [1, 2])
- Booleans: true and false
- Null: null
Comparison Operators
- == (equal)
- === (identical)
- != (not equal)
- !== (not identical)
- < (less than)
- > (greater than)
- <= (less than or equal to)
- >= (greater than or equal to)
- matches (regex match)
Examples:
- order.items.count >= 5
Logical Operators
- not or !
- and or &&
- or or ||
Examples:
- Seller.id == 1234 and item.shipmentType.isDropShipping
Array Operators
- in (contain)
- not in (does not contain)
Examples:
- Seller.id in [1234, 5678, 9101]
Numeric Operators
- .. (range)
Examples:
- seller.rating in 4..5
Ternary Operators
- foo ? ‘yes’ : ‘no’
- foo ?: ‘no’ (equal to foo ? foo : ‘no’)
- foo ? ‘yes’ (equal to foo ? ‘yes’ : “)
Examples:
- item.shipmentType.isDropShipping ? 4 : 5
Checklist to Roll Out Transaction Rule Engine
As a long-term goal, we want to move all transactions from the legacy code to the dynamic mechanism of a Transaction Rule Engine. In doing so, we intend to bring the finance areas of our customers to the next level. In order to make a proper roll out, please take the following steps into consideration:
What are the steps to create a rule in the Transaction Rule Engine?
- Consider if a transaction rule is based on Seller or order item-level. Please note: if you need order-level rules, please communicate with your Product Manager regarding the proper way to calculate the transaction rule.
- Take your time and write all possible business cases for the transaction rule that you want to apply. Different countries often have different logics and require different contexts for the same rule. Therefore, before sending a request to Seller Center, please send possible business cases and the context that needs to be developed (in order to save time and money).
- Once the request is sent, the Product Manager will discuss with you whether any development is required.
How do I roll out a transaction rule within my company?
Currently, rules can be set on Seller Center-side. As a mid-term goal, we are planning to give rights to admin users to set variables and transaction rules. It is recommended to use an Excel table to organize the content that is needed for transaction rules. Please ask your Seller Center Product Manager to provide you with a form.
- First, add variables that are needed for a transaction rule (if necessary).
- Check with your Seller Center Product Manager if any macros need to be added. If so, they will add macros in order to see the macros’ values in the calculation.
- Now you can create a transaction rule.
- Edit variable values in a separate tab. As an important part of the roll out, make sure that variable values are added properly by an Account Manager. Only when values are edited, you can enable a rule. Therefore, it is recommended to send an Account Manager an email communicating a deadline to add the values.
- Once variable values are added, you can enable the rule.
Where to see the applied rules
The transactions tables on the database schema will not change. This means that Sellers and Ventures will see all transactions generated by the rule engine in the same place.
In the “Details” column on the Transaction Overview screen, an extra text will be added to indicate that a transaction rule has been generated by the rule engine.
An Example of a details cell:
“Book: Git for dummies, Generated by Rule: ‘New Rule 1, Reference: 4743′”