Retail POS APIs help you to easily build extensions or new features to the POS app. For example, if you are extending the Retail POS application to add new features in which to want to get product details, change prices, or add items to a cart. you can consume APIs that will do the work for you. To do this, you need to call the APIs to do the work. The POS API simplifies the extension pattern and provides continuous support to build the extensions.
Extension patterns have been unified across commerce runtime (CRT), POS, and Hardware station (HWS) by following the request/response pattern. All the POS APIs are exposed as request/response like CRT and HWS.
POS APIs are categorized into three different scenarios:
Consume – Consume public APIs in your extension.
Extend – Override public APIs to do some additional logic.
Create – Create new APIs using the exposed POS interface, which can be used across extensions.
Many APIs can be consumed in extensions. For example, if you want to change the price of the item based on an external web service call, you can call PriceOverrideOperationRequest to change the price of the item. Within the consume, the APIs are sub categorized by module like cart, peripherals, store operations, etc.
Note
A list of the all of the APIs is available in Pos.Api.d.ts, which is part of the Retail SDK (...Retail SDK\POS\Extensions\Pos.Api.d.ts). Extensions must consume only the exposed request and response from the POS.Api.d.ts and no modification is allowed to Pos.Api.d.ts. Extensions should not consume or update any POS APIs, properties, methods, or handlers directly from POS commerce or sessions objects.
How to consume APIs in your extension
Use the following steps to consume Retail APIs in your extensions.
Import the API in your extension file.
For example, if you want to consume the save attribute on cart API in your extension, then you need to add the following import statements.
The pattern is import { api name } from "PosApi/Consume/Module name";
import { SaveAttributesOnCartClientRequest, SaveAttributesOnCartClientResponse } from "PosApi/Consume/Cart";
Import the client entities and proxy entities if necessary.
import { ClientEntities } from "PosApi/Entities";
import { ProxyEntities } from "PosApi/Entities";
Declare the API variable and execute it using the POS runtime, which you can access the runtime by using: this.context.runtime.executeAsync("api name")
For example, if you want to execute the tender removal, use SaveAttributesOnCartClientRequest api, and refer to the following steps.
let attributeValue: ProxyEntities.AttributeTextValue = new ProxyEntities.AttributeTextValueClass();
attributeValue.Name = PreEndTransactionTrigger.B2B_CART_ATTRIBUTE_NAME;
attributeValue.TextValue = "Yes";
let attributeValues: ProxyEntities.AttributeValueBase[] = [attributeValue];
let saveAttributesOnCartRequest: SaveAttributesOnCartClientRequest<SaveAttributesOnCartClientResponse> =
new SaveAttributesOnCartClientRequest(attributeValues);
result = this.context.runtime.executeAsync(saveAttributesOnCartRequest);
Samples showing how to access APIs
Get Current cart
// Gets the current cart.
let currentCart: ProxyEntities.Cart;
return this.context.runtime.executeAsync<GetCurrentCartClientResponse>(new GetCurrentCartClientRequest())
.then((getCurrentCartClientResponse: ClientEntities.ICancelableDataResult<GetCurrentCartClientResponse>):
Promise<ClientEntities.ICancelableDataResult<GetCustomerClientResponse>> => {
currentCart = getCurrentCartClientResponse.data.result;
Get Current customer added to cart
// Gets the current customer.
let result: Promise<ClientEntities.ICancelableDataResult<GetCustomerClientResponse>>;
if (!ObjectExtensions.isNullOrUndefined(currentCart) && !ObjectExtensions.isNullOrUndefined(currentCart.CustomerId)) {
let getCurrentCustomerClientRequest: GetCustomerClientRequest<GetCustomerClientResponse> =
new GetCustomerClientRequest(currentCart.CustomerId);
result = this.context.runtime.executeAsync<GetCustomerClientResponse>(getCurrentCustomerClientRequest);
} else {
result = Promise.resolve({ canceled: true, data: new GetCustomerClientResponse(null) });
}
Force void transaction
// Force void tarnsaction.
let forceVoidTransactionRequest: VoidTransactionOperationRequest<VoidTransactionOperationResponse> =
new VoidTransactionOperationRequest<VoidTransactionOperationResponse>(false, this.context.logger.getNewCorrelationId());
this.context.runtime.executeAsync(forceVoidTransactionRequest).then((value: ICancelableDataResult<VoidTransactionOperationResponse>) => {
this.currentCart(JSON.stringify(value.data.cart));
}).catch((err: any) => {
this.currentCart(JSON.stringify(err));
});
Cart
The following table lists APIs exposed to perform cart-related functionality.
POS API
Description
Release
AddPreprocessedTenderLineToCartClientRequest
Adds the pre-processed tender line to the cart.
10.0.14
AddTenderLineToCartClientRequest
Adds the tender line to the cart.
10.0.14
ConcludeTransactionClientRequest
Concludes the transaction.
10.0.14
GetCurrentCartClientRequest
Gets the current cart.
10.0.14
GetKeyedInPriceClientRequest
Gets the keyed in price.
10.0.14
GetPickupDateClientRequest
Gets the pickup date.
10.0.14
GetReasonCodeLinesClientRequest
Gets the reason code.
10.0.14
GetReceiptEmailAddressClientRequest
Gets the receipt email address.
10.0.14
GetShippingDateClientRequest
Gets the shipping date.
10.0.14
RefreshCartClientRequest
Refresh the current cart with the cart data from the server.
10.0.14
ResumeSuspendedCartClientRequest
Resumes the suspended transaction based on the ID passed.
10.0.14
SaveAttributesOnCartClientRequest
Saves the attributes on the cart.
10.0.14
SaveAttributesOnCartLinesClientRequest
Saves the attributes on the cart line.
10.0.14
SaveExtensionPropertiesOnCartClientRequest
Saves the extension properties on the cart.
10.0.14
SaveExtensionPropertiesOnCartLinesClientRequest
Saves the extension properties on the cart line.
10.0.14
SaveReasonCodeLinesOnCartClientRequest
Saves the reason code lines on the cart.
10.0.14
SaveReasonCodeLinesOnCartLinesClientRequest
Saves the reason code lines on the cart line.
10.0.14
SelectSalesLinesForPickUpClientRequest
Select the sales lines for pickup.
10.0.14
SetCartAttributesClientRequest
Sets the cart attribute.
10.0.14
ShowChangeDueClientRequest
Shows the change due dialog.
10.0.14
AddAffiliationOperationRequest
Adds affiliation to the cart.
10.0.14
AddItemToCartOperationRequest
Add items to the cart.
10.0.14
CalculateTotalOperationRequest
Calculate the total for the cart.
10.0.14
ChangeCartLineUnitOfMeasureOperationRequest
Changes the cart line unit of measure.
10.0.14
CreateCustomerOrderOperationRequest
Creates the customer order.
10.0.14
CreateCustomerQuoteOperationRequest
Creates the customer quote.
10.0.14
CustomerAccountDepositOperationRequest
10.0.14
DepositOverrideOperationRequest
Overrides the deposit amount.
10.0.14
EditCustomerOrderOperationRequest
Edit the customer order.
10.0.14
LineDiscountAmountOperationRequest
Add line discount amount to the cart line.
10.0.14
LineDiscountPercentOperationRequest
Add line discount percent to the cart line.
10.0.14
OverrideLineTaxFromListOperationRequest
Override the cart line tax from the list.
10.0.14
OverrideLineTaxOperationRequest
Override the cart line tax.
10.0.14
OverrideTransactionTaxOperationRequest
Override the transaction tax.
10.0.14
PickupAllOperationRequest
Picks up the order.
10.0.14
PriceOverrideOperationRequest
Override the price for the cart line.
10.0.14
SetCartLineCommentOperationRequest
Sets the cart line comment.
10.0.14
SetCartLineQuantityOperationRequest
Sets the cart line quantity.
10.0.14
SetCustomerOnCartOperationRequest
Sets the customer on the cart.
10.0.14
SetTransactionCommentOperationRequest
Sets the transaction comment.
10.0.14
SuspendCurrentCartOperationRequest
Suspends the current transaction.
10.0.14
TotalDiscountAmountOperationRequest
Add total discount amount to the transaction.
10.0.14
TotalDiscountPercentOperationRequest
Add total discount percent to the transaction.
10.0.14
VoidCartLineOperationRequest
Voids the cart line.
10.0.14
VoidTenderLineOperationRequest
Voids the tender line.
10.0.14
VoidTransactionOperationRequest
Voids the transaction.
10.0.14
CreateEmptyCartServiceRequest
Creates empty cart.
10.0.14
GetTaxOverridesServiceRequest
Gets the tax override list.
10.0.14
UpdateTenderLineSignatureServiceRequest
Updates the tender line signature data.
10.0.14
CarryoutSelectedProductsOperationRequest
Marks the selected line as carry out.
10.0.14
AddCouponsOperationRequest
Add coupon to the transaction.
10.0.14
CreateNonSalesTransactionServiceRequest
Create non sales transaction cart.
10.0.14
ReturnTransactionOperationRequest
Returns the transaction.
10.0.14
AddLoyaltyCardToCartOperationRequest
Adds loyalty card to the transaction.
10.0.14
ReturnCartLineOperationRequest
Returns the cart line.
10.0.14
ReturnItemOperationRequest
Returns the item.
10.0.14
AddExpenseAccountLineToCartOperationRequest
Add expense account line to the cart.
10.0.14
ShipAllCartLinesOperationRequest
Ships all the cart lines.
10.0.14
ShipSelectedCartLinesOperationRequest
Ships the selected cart line.
10.0.14
PickupSelectedOperationRequest
Marks the included lines for pickup
10.0.16
Payments
The following table lists APIs exposed to perform payment-related functionality.
POS API
Description
Release
GetGiftCardByIdServiceRequest
Gets the gift card ID.
10.0.12
GetPaymentCardTypeByBinRangeClientRequest
Get the card type bin range.
10.0.12
GetSignatureClientRequest
Shows the signature capture dialog in POS or sends the message to the signature capture device based on the configuration.
10.0.15
Peripherals
The following table lists APIs exposed to perform peripheral-related functionality.
This article describes how to use triggers to capture events that occur before and after any Microsoft Dynamics 365 Commerce Store Commerce app operations.
This article provides information about how you can create point of sale (POS) extensions by using the new independent POS extension model and sealed software development kit (SDK).