Commerce runtime (CRT) services

Commerce runtime (CRT) is a collection of portable .NET libraries that contain the core business logic for the commerce channel and pricing functionality. To add or modify any business logic, you should customize CRT. Store Commerce calls CRT to request that it performs business logic. CRT processes the request and then sends the response back to point of sale. POS is like a thin client, all the business logic should be done in CRT.

A CRT service is a group of requests/responses. Anytime that you do something in POS, POS sends a request to Commerce Scale Unit, and Commerce Scale Unit calls CRT. CRT processes the request and sends back the response.

This article shows some important requests/responses that you can customize for your business scenario.

There are three main layers in CRT:

• Services
• Workflow
• Data Access

All CRT customization for business logic can be done in Services, Workflow or Data Access layers, other core layers that are required for CRT to work are runtime, authentication, and data access managers and you should avoid any customization on these layers.

Note

Detailed information about all CRT classes can be found in the Retail SDK, which is found at RetailSDK\Documents\CommerceRuntimeMessages.chm.

Overall flow

The overall flow looks like this:

CRT service request < > Zero or more workflow requests < > Zero or more data access requests

For example, multiple workflow and data access requests are called to perform the Create sales order service request.

CRT services

Each CRT service contains one or more requests/responses. For example, the Customer service in CRT contains all the customer-related requests/responses. Each request/response is run in a different flow.

Default CRT services

Many services in CRT support the functionality of the channel and store operations. You can add your own services or extend the existing services. The following table describes some of the services that you might customize for various business services.

For more information about each service, see the CRT request/response document in the Retail software development kit (SDK), at …\RetailSDK\Code\Documents\CommerceRuntimeMessages.chm.

Service	Description
AddressService	This service verifies addresses and gets location information, such as cities, counties, or states.
BarcodeService	This service processes the barcode that was scanned, based on the mask and barcode types, and calculates the quantity and price from the barcode.
CartService	This service gets the cart from the transaction and sales transaction service from the transaction tables.
ChargeService	This service implements logic that calculates automatic charges, price charges, and shipping charges for transactions.
CouponService	This service validates and updates coupon-related requests.
CurrencyService	This service converts currencies, based on exchange rates.
CustomerService	This service contains customer related operations such as Save customer, purchase history, get customer and customer balance.
EmployeeService	This service gets employee-related information and employees by store.
FormattingService	This service implements logic for the format of numbers, currencies, and dates.
GiftCardService	This service provides information about internal activities that are related to gift cards, such as issuing the gift card, getting the balance, and adding value.
LoyaltyService	This service implements a program that rewards repeat customers.
NotificationService	This service maintains the POS notification service.
PaymentService	This service lets you connect your online store to a payment service to provide credit card authorization and use preconfigured payment processing. You can also extend the payment service to add additional third-party payment processors.
ProductService	This service gets product-related and variant-related information.
ProductsService	This service gets information that is related to products and variants.
PricingService	This service gets the price of an item in real time. The price is adjusted, based on the base price and any applicable discounts. Discounts can be customized for each retailer.
ProductAvailabilityService	This service calculates the quantities of products that are available to sell.
ReasonCodeService	This service calculates and gets the required reason code for POS operations or any workflow.
ReceiptService	This service gets and formats the receipt details.
RoundingService	This service rounds the tender amount, based on the tender type and store.
SalesOrderService	This service creates a sales order, based on a customer shopping cart.
SearchProductsService	This service searches products, based on the input text.
ShippingService	This service calculates shipping costs and determines shipping options for the current order.
StockCountService	This service creates, commits, and synchronizes stock journals.
StoreOperationService	This service maintains store-related operation services, such as Save and Drop, Tender declaration, and Search journal.
TaxService	This service calculates the sales tax for the current order. You can use sales tax information provided, or from a third-party sales tax service.
TotalingService	This service calculates the totals on the sales transactions and sales lines.

For extension scenarios, you can add CRT triggers, create new services, and override any of the requests in the service class. For information about how to extend and understand CRT extension patterns, see Commerce runtime (CRT) extensibility.

Note

CRT extension code should not refer to or use any of the CRT business logic classes, methods, or handlers (such as classes from Runtime.Workflow, Runtime.Services, or Runtime.DataServices). These classes are not backward compatible, which could break extensions during an upgrade. Extensions should only use request, response, and entity classes from Runtime.*.Messages, Runtime.Framework, Runtime.Data, and Runtime.Entities.

AddressService

The Address service supports the following requests/responses for various extension scenarios.

Request	Purpose
GetCountryRegionsServiceRequest	This request gets the list of countries and regions that are supported.
GetStateProvincesServiceRequest	This request gets the list of states or provinces that are supported for the country or region.
GetCitiesServiceRequest	This request gets the list of cities that are supported for the state or region.
GetDistrictServiceRequest	This request gets the list of districts that are supported.
GetZipCodesServiceRequest	This request gets the list of ZIP Codes that are supported.
GetFromZipPostalCodeServiceRequest	This request gets the list of postal codes supported.
GetAddressFormattingServiceRequest	This request gets the address format for the specified country or region.

BarcodeService

Request	Purpose
ProcessMaskSegmentsServiceRequest	This request processes the barcode, based on the barcode mask configuration.
GetBarcodeTypeServiceRequest	This request gets the types of barcodes that are supported.
CalculateQuantityFromPriceServiceRequest	This request calculates the price and quantity, based on the barcode that is scanned or entered.

CartService

It's possible to generate extensions that can cause parallel execution in an additional thread, as shown in the following example:

cartService.Execute(createRequest(calculateSalesTransactionServiceRequest, CalculationModes.Totals));

The example above could generate high CPU usage in a system due to concurrent access to both the insert and FindEntry functions of the dictionary due to parallel execution.

Request	Purpose
GetSalesTransactionsServiceRequest	This request gets the sales transaction from Headquarters.
GetCartServiceRequest	This request gets the cart from the sales transaction table by using the cart ID.
CalculateSalesTransactionServiceRequest	This request calculates the various sales transaction totals, based on the specified calculation mode.
CalculateEstimatedShippingAuthorizationAmountServiceRequest	This request calculates the estimated shipping authorization amount on the transaction.
ConvertSalesTransactionToCartServiceRequest	This request converts the sales transaction to a cart transaction, based on transaction ID that is passed.

CouponService

Request	Purpose
UpdateCouponCodesOnCartServiceRequest	This request updates the coupon codes status in Headquarters, based on the coupons that are used in the cart.
ValidateCouponCodesServiceRequest	This request validates the coupon code that is entered in the transactions.
UpdateCouponUsageServiceRequest	This request updates coupon usage for the transaction.

CustomerService

Request	Purpose
SaveCustomerServiceRequest	This request is called when you save a customer from the POS.
GetCustomersServiceRequest	This request gets the selected customer details.
CustomersSearchServiceRequest	This request is run when you search for a customer from the POS.
GetCustomerGroupsServiceRequest	This request gets the customer group details.
InitiateLinkToExistingCustomerServiceRequest	This request is an internal request for backward compatibility.
FinalizeLinkToExistingCustomerServiceRequest	This request is an internal request for backward compatibility.
UnlinkFromExistingCustomerServiceRequest	This request is an internal request for backward compatibility.
GetCustomerBalanceServiceRequest	This request gets the balance of the customer's account.
GetOrderHistoryServiceRequest	This request gets the customer's order history.
GetPurchaseHistoryServiceRequest	This request gets the history of the customer's recent purchases.
CustomerSearchByFieldsServiceRequest	This request is run when you search customer by using fields such as name, phone number etc. (hint search).
GetCustomerSearchFieldsServiceRequest	This request gets the list of customer search fields (hint fields).

PricingService

Request	Purpose
CalculatePricesServiceRequest	This request calculates the price for each item that is added to the cart and on the search screen.
CalculateDiscountsServiceRequest	This request calculates the discount for each item that is added to the cart.
GetIndependentPriceDiscountServiceRequest	This request calculates the price for each item on the price check screen and in other non-transaction-related flows.
ValidateDiscountsServiceRequest	This request validates the discount that is entered, based on the employee.
GetAllPeriodicDiscountsServiceRequest	This request gets all the periodic discounts that are configured.
GetDiscountCodesServiceRequest	This request gets all the discount codes that are configured.

ProductService

Request	Purpose
ProductSearchServiceRequest	This request gets the product list, based on the search text from the POS. (This is an old request. For customization, use the new SearchProductsServiceRequest request instead.)
GetProductServiceRequest	This request gets the product, based on the product ID.
GetProductRefinersRequest	This request retrieves the product refiner values.

ProductsService

Request	Purpose
GetProductsServiceRequest	This request gets the products, based on the products IDs that are provided.
GetVariantProductsServiceRequest	This request gets specific variations of master type products.

ReasonCodeService

Request	Purpose
GetReasonCodesServiceRequest	This request gets the required reason code for the workflow or POS operation.
CalculateRequiredReasonCodesServiceRequest	This request calculates the required reason code for the workflow or POS operation.
CalculateCartRequiredReasonCodesServiceRequest	This request calculates the required reason code for the cart workflow.
CalculateDropAndDeclareTransactionRequiredReasonCodesServiceRequest	This request calculates the required reason code for the drop and tender declaration transaction.
CalculateNonSalesTransactionRequiredReasonCodesServiceRequest	This request calculates the required reason code for the non-sales transaction, such as tender declaration.
GetReturnOrderReasonCodesServiceRequest	This request gets the required reason code for the return transaction.
ValidateReasonCodeLineForUpdateServiceRequest	This request validates the reason code lines that are added during the save cart request.

ReceiptService

Request	Purpose
GetReceiptServiceRequest	This request gets the receipt type and generates the receipt data, based on the receipt type.
GetCustomReceiptFieldServiceRequest	Override this request, and add custom logic for your custom fields that are added in the receipt.
GetEmailReceiptServiceRequest	This request gets the formatted receipts that will be used for print and email scenarios.
PopulateTaxSummaryIndiaServiceRequest	This request populates the tax summary for India transaction.

SearchProductsService

Request	Purpose
SearchProductsServiceRequest	This request is run when you search for a product from the POS.

TaxService

Request	Purpose
CalculateTaxServiceRequest	This request calculates taxes on the transaction.
AssignTaxCodesServiceRequest	This request assigns tax codes on the transaction's taxable items before the tax calculation. The default tax calculation handler of the CalculateTaxServiceRequest request uses this message.
PopulateTaxRatesRequest	This request populates tax rates for the recalled transaction. No tax percentage information is persisted for tax lines. This message handler restores the information.

Workflow layer

On top of the Services layer is the Workflow layer. A workflow is a collection of services and business logic that together define business processes. For example, when a customer adds an item to the cart, you can use a workflow to get the price, do validation, check the inventory quantity, calculate shipping, calculate tax, and calculate discounts. You can customize the existing workflows, or you can create new workflows. You can even use a workflow to connect to a third-party system as part of your business processes.

Just like services, workflows use the request/response pattern. The request object inherited from the base CRT Request class. The response object inherited from the base CRT Response class. A workflow also has a request handler class that extends the WorkflowRequestHandler<TRequest, TResponse> class. To create a workflow, you create a request class and a response class, and you then create a request handler class that contains the business logic for the workflow.

For example, when you create a cash-and-carry transaction or a customer order, many different steps or workflows are completed before the order is created. One of the workflow steps in the order process is the Save cart request. The Save cart request workflow is responsible for saving any changes that are made to the cart from the POS. For example, when you add an item to the cart, change the quantity, and so on, anything that you do in the POS will cause a call to the SaveCart to save the changes to the POS and database.

Default workflows and handlers

The following table lists the default workflow requests and response. CRT services call the workflows request and response based on the operation you perform in POS. You can customize any of these workflows request and response according to your business scenario.

Request	Handler	Purpose
AddOrderInvoiceToCartRequest	AddOrderInvoiceToCartRequestHandler	This request adds the invoice to the cart as a cart line.
AddOrRemoveDiscountCodesRequest	AddOrRemoveDiscountCodesRequestHandler	This request adds discount codes to the cart or removes them from the cart.
CancelOrderRequest	CancelOrderRequestHandler	This request is triggered when you cancel an order from the POS.
CopyCartRequest	CopyCartRequestHandler	This request creates an identical shopping cart that has the specified cart type.
GetAddressRequest	GetAddressRequestHandler	This request gets the address from the list.
GetCardPaymentAcceptPointRequest	GetCardPaymentAcceptPointRequestHandler	This request shows the accepting page for card payment.
GetCartRequest	GetCartRequestHandler	This request gets the shopping cart, based on the cart search criteria.
GetDiscountCodesRequest	GetDiscountCodesRequestHandler	This request gets the discount codes.
GetOrdersRequest	GetOrdersRequestHandler	This request gets sales orders.
GetPromotionsRequest	GetPromotionsRequestHandler	This request gets the shopping cart together with promotion lines for the cart and the cart items.
GetScanResultRequest	GetScanResultRequestHandler	This request gets the entity details, based on the details that are scanned or typed.
GetSupportedCardTypesRequest	GetSupportedCardTypesRequestHandler	This request retrieves the cart types that are supported for the specified currency.
IssueOrAddToGiftCardRequest	IssueOrAddToGiftCardRequestHandler	This request issues a gift card or adds to a gift card's balance.
PickAndPackOrderRequest	PickAndPackOrderRequestHandler	This request represents a request for picking list creation and packing slip creation for a customer order.
PickupAtStoreRequest	PickupAtStoreRequestHandler	This request represents a request for pick-up at the store.
RecalculateOrderRequest	RecalculateOrderRequestHandler	This request represents a request for the recalculate order workflow.
RecallCustomerOrderRequest	RecallCustomerOrderRequestHandler	This request gets sales orders and converts them into a cart.
RecallSalesInvoiceRequest	RecallSalesInvoiceRequestHandler	This request gets invoices.
ResumeCartRequest	ResumeCartRequestHandler	This request represents a request to resume a cart that was suspended.
SaveCartLinesRequest	SaveCartLinesRequestHandler	This request represents a request for create, update, delete, or void operations on the cart line.
SaveCartRequest	SaveCartRequestHandler	This request is triggered when you make any changes in that POS that affect the cart.
SaveCustomerOrderRequest	SaveCustomerOrderRequestHandler	This request initiates a request to save the customer order, based on the specified cart identifier and payment card information.
SaveReasonCodeLineRequest	SaveReasonCodeLineRequestHandler	This request adds or updates a reason code on the cart line.
SaveTenderLineRequest	SaveTenderLineRequestHandler	This request adds, removes, or updates a tender line for the given shopping cart.
SaveVoidTransactionRequest	SaveVoidTransactionRequestHandler	This request voids a transaction.
SubmitSalesTransactionRequest	SubmitOrderRequestHandler	This request initiates a request to submit the sales transaction, based on the specified cart identifier.
SuspendCartRequest	SuspendCartRequestHandler	This request represents a request to suspend the cart.
TransferCartRequest	TransferCartRequestHandler	This request transfers the specified shopping cart.
UpdateCommissionSalesGroupRequest	UpdateCommissionSalesGroupHandler	This request encapsulates a request for updating the sales representative on the cart or the cart line.
UploadOrderRequest	UploadOrderRequestHandler	This request uploads the sales order.
ValidateCartForCheckoutRequest	ValidateCartForCheckoutRequestHandler	This request validates the cart for checkout.