Retail Server customer and consumer APIs

Important

This topic applies to Dynamics 365 for Retail and Dynamics 365 for Finance and Operations, Enterprise edition.

This article provides an overview of the APIs that are available across various roles, and that can be used by various clients. The focus is on customer-facing application clients and eCommerce clients.

Overview

  • Retail Server business data and operations are available to any connected device through the OData Web API, across both employee (point of sale) scenarios and customer (online store) scenarios.
  • The embedded commerce runtime (CRT) enables a unified omni-channel platform.
  • The application programming interfaces (APIs) are stateless and can process requests from many channels.
  • The APIs have a linear scale-out model (“brick” scale-out).
  • You use a composition pattern for plug-and-play customizations.
  • The APIs are built on the .NET stack by using C#.

Roles

Every request to Retail Server (via retail proxy) operates under three main roles:

  • CommerceRole.Employee
  • CommerceRole.Anonymous
  • CommerceRole.Customer

The Anonymous and Customer roles apply to eCommerce (customer/consumer) scenarios. The Anonymous role is used for requests that represent an eCommerce customer who hasn't signed in. The Customer role is used for requests that represent an eCommerce customer who has been authenticated and has signed in. A role filter is applied to every API that is exposed in Retail Server. For eCommerce scenarios, you can use only APIs that have either CommerceRole.Anonymous or CommerceRole.Customer associated with them.

APIs that are available for an authenticated customer role

CartManager APIs

  • Task<SalesOrder> CartManager.Checkout(String id, String receiptEmail, TokenizedPaymentCard tokenizedPaymentCard, String receiptNumberSequence, IEnumerable<CartTenderLine> cartTenderLines)
  • Task<Cart> CartManager.Copy(String id, Int32 targetCartType)
  • Task<Cart> CartManager.AddCartLines(String id, IEnumerable<CartLine> cartLines)
  • Task<Cart> CartManager.UpdateCartLines(String id, IEnumerable<CartLine> cartLines)
  • Task<CartDeliveryPreferences> CartManager.GetDeliveryPreferences(String id)
  • Task<PagedResult<SalesLineDeliveryOption>> CartManager.GetLineDeliveryOptions(String id, IEnumerable<String> cartLineIds, Address shippingAddress, QueryResultSettings queryResultSettings)
  • Task<PagedResult<DeliveryOption>> CartManager.GetDeliveryOptions(String id, Address shippingAddress, QueryResultSettings queryResultSettings)
  • Task<Cart> CartManager.UpdateLineDeliverySpecifications(String id, IEnumerable<LineDeliverySpecification> lineDeliverySpecifications)
  • Task<Cart> CartManager.UpdateDeliverySpecification(String id, DeliverySpecification deliverySpecification)
  • Task<PagedResult<Product>> CartManager.GetProductsInCart(String id, QueryResultSettings queryResultSettings)
  • Task<CartPromotions> CartManager.GetPromotions(String id)
  • Task<Cart> CartManager.AddDiscountCode(String id, String discountCode)
  • Task<Cart> CartManager.RemoveDiscountCodes(String id, IEnumerable<String> discountCodes)
  • Task<Cart> CartManager.RemoveCartLines(String id, IEnumerable<String> cartLineIds)
  • Task<PagedResult<Cart>> CartManager.Search(CartSearchCriteria cartSearchCriteria, QueryResultSettings queryResultSettings)
  • Task<CardPaymentAcceptPoint> CartManager.GetCardPaymentAcceptPoint(String id, CardPaymentAcceptSettings cardPaymentAcceptSettings)
  • Task<CardPaymentAcceptResult> CartManager.RetrieveCardPaymentAcceptResult(String resultAccessCode)
  • Task<Cart> CartManager.Read(String id, ICollection<String> expandProperties)
  • Task<Cart> CartManager.Update(Cart entity)
  • Task<Cart> CartManager.Create(Cart entity)CartsController.GetEntityByKey()

ProductCatalogManager and CategoryManager APIs

  • Task<PagedResult<ProductCatalog>> ProductCatalogManager.GetCatalogs(Int64 channelId, Boolean activeOnly, QueryResultSettings queryResultSettings)
  • Task<PagedResult<Category>> CategoryManager.GetCategories(Int64 channelId, QueryResultSettings queryResultSettings)

CommerceList and CommerceListManager APIs

  • Task<PagedResult<CommerceList>> CommerceListManager.GetByCustomer(String customerId, QueryResultSettings queryResultSettings)
  • Task<CommerceList> CommerceListManager.AddLines(Int64 id, IEnumerable<CommerceListLine> commerceListLines)
  • Task<CommerceList> CommerceListManager.UpdateLines(Int64 id, IEnumerable<CommerceListLine> commerceListLines)
  • Task<CommerceList> CommerceListManager.RemoveLines(Int64 id, IEnumerable<CommerceListLine> commerceListLines)
  • Task<CommerceList> CommerceListManager.MoveLines(IEnumerable<CommerceListLine> commerceListLines, Int64 destinationId)
  • Task<CommerceList> CommerceListManager.CopyLines(IEnumerable<CommerceListLine> commerceListLines, Int64 destinationId)
  • Task<CommerceList> CommerceListManager.AddContributors(Int64 id, IEnumerable<CommerceListContributor> commerceListContributors)
  • Task<CommerceList> CommerceListManager.RemoveContributors(Int64 id, IEnumerable<CommerceListContributor> commerceListContributors)
  • Task<CommerceList> CommerceListManager.CreateInvitations(Int64 id, IEnumerable<CommerceListInvitation> commerceListInvitations)
  • Task CommerceListManager.AcceptInvitation(String invitationToken, String customerId)
  • Task<CommerceList> CommerceListManager.Read(Int64 id, ICollection<String> expandProperties)
  • Task<CommerceList> CommerceListManager.Create(CommerceList entity)
  • Task<CommerceList> CommerceListManager.Update(CommerceList entity)
  • Task CommerceListManager.Delete(CommerceList entity)

CustomerManager APIs

  • Task<PagedResult<SalesOrder>> CustomerManager.GetOrderHistory(String accountNumber, QueryResultSettings queryResultSettings)
  • Task<PagedResult<PurchaseHistory>> CustomerManager.GetPurchaseHistory(String accountNumber, QueryResultSettings queryResultSettings)
  • Task<Customer> CustomerManager.Read(String accountNumber, ICollection<String> expandProperties)
  • Task<Customer> CustomerManager.Update(Customer entity)

StoreOperationsManager and OrgUnitManager APIs

  • Task<PagedResult<CardTypeInfo>> StoreOperationsManager.GetCardTypes(QueryResultSettings queryResultSettings)
  • Task<PagedResult<String>> StoreOperationsManager.GetSupportedPaymentCardTypes(QueryResultSettings queryResultSettings)
  • Task<PagedResult<CountryRegionInfo>> StoreOperationsManager.GetCountryRegionsByLanguageId(String languageId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<DeliveryOption>> StoreOperationsManager.GetDeliveryOptions(QueryResultSettings queryResultSettings)
  • Task<GiftCard> StoreOperationsManager.GetGiftCard(String giftCardId)
  • Task<LinkToExistingCustomerResult> StoreOperationsManager.InitiateLinkToExistingCustomer(String email, String activationToken, String emailTemplateId, IEnumerable<NameValuePair> emailProperties)
  • Task StoreOperationsManager.UnlinkFromExistingCustomer()
  • Task<LoyaltyCard> StoreOperationsManager.IssueLoyaltyCard(LoyaltyCard loyaltyCard)
  • Task<LoyaltyCard> StoreOperationsManager.GetLoyaltyCard(String cardNumber)
  • Task<PagedResult<LoyaltyCard>> StoreOperationsManager.GetCustomerLoyaltyCards(String accountNumber, QueryResultSettings queryResultSettings)
  • Task<PagedResult<LoyaltyCardTransaction>> StoreOperationsManager.GetLoyaltyCardTransactions(String cardNumber, String rewardPointId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<StateProvinceInfo>> StoreOperationsManager.GetStateProvinces(String countryRegionId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<TenderType>> StoreOperationsManager.GetTenderTypes(QueryResultSettings queryResultSettings)
  • Task<PagedResult<OrgUnit>> OrgUnitManager.ReadAll(QueryResultSettings queryResultSettings, ICollection<String> expandProperties)
  • Task<PagedResult<OrgUnitLocation>> OrgUnitManager.GetOrgUnitLocationsByArea(SearchArea searchArea, QueryResultSettings queryResultSettings)
  • Task<PagedResult<OrgUnitAvailability>> OrgUnitManager.GetAvailableInventory(String itemId, String variantId, String barcode, QueryResultSettings queryResultSettings)
  • Task<PagedResult<OrgUnitAvailability>> OrgUnitManager.GetAvailableInventoryNearby(IEnumerable<ItemUnit> itemIds, SearchArea searchArea, QueryResultSettings queryResultSettings)
  • Task<TillLayout> OrgUnitManager.GetTillLayout()
  • Task<ChannelConfiguration> OrgUnitManager.GetOrgUnitConfiguration()
  • Task<PagedResult<OrgUnit>> OrgUnitManager.Search(SearchStoreCriteria storeSearchCriteria, QueryResultSettings queryResultSettings)
  • Task<OrgUnit> OrgUnitManager.Read(String orgUnitNumber, ICollection<String> expandProperties)

ProductManager APIs

  • Task<PagedResult<Product>> ProductManager.ReadAll(QueryResultSettings queryResultSettings, ICollection<String> expandProperties)
  • Task<PagedResult<Product>> ProductManager.Search(ProductSearchCriteria productSearchCriteria, QueryResultSettings queryResultSettings)
  • Task<SimpleProduct> ProductManager.GetById(Int64 recordId, Int64 channelId)
  • Task<PagedResult<ProductSearchResult>> ProductManager.SearchByCategory(Int64 channelId, Int64 catalogId, Int64 categoryId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductSearchResult>> ProductManager.SearchByText(Int64 channelId, Int64 catalogId, String searchText, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductRefiner>> ProductManager.GetRefinersByCategory(Int64 catalogId, Int64 categoryId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductRefiner>> ProductManager.GetRefinersByText(Int64 catalogId, String searchText, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductRefinerValue>> ProductManager.GetRefinerValuesByCategory(Int64 catalogId, Int64 categoryId, Int64 refinerId, Int32 refinerSourceValue, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductRefinerValue>> ProductManager.GetRefinerValuesByText(Int64 catalogId, String searchText, Int64 refinerId, Int32 refinerSourceValue, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductSearchResult>> ProductManager.RefineSearchByCategory(Int64 channelId, Int64 catalogId, Int64 categoryId, IEnumerable<ProductRefinerValue> refinementCriteria, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductSearchResult>> ProductManager.RefineSearchByText(Int64 channelId, Int64 catalogId, String searchText, IEnumerable<ProductRefinerValue> refinementCriteria, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductDimensionValue>> ProductManager.GetDimensionValues(Int64 recordId, Int64 channelId, Int32 dimension, IEnumerable<ProductDimensionValue> matchingDimensionValues, QueryResultSettings queryResultSettings)
  • Task<PagedResult<SimpleProduct>> ProductManager.GetVariantsByDimensionValues(Int64 recordId, Int64 channelId, IEnumerable<ProductDimensionValue> matchingDimensionValues, QueryResultSettings queryResultSettings)
  • Task<PagedResult<SimpleProduct>> ProductManager.GetVariantsByComponentsInSlots(Int64 recordId, Int64 channelId, IEnumerable<ComponentInSlotRelation> matchingSlotToComponentRelationship, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductComponent>> ProductManager.GetDefaultComponents(Int64 recordId, Int64 channelId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductComponent>> ProductManager.GetSlotComponents(Int64 recordId, Int64 channelId, Int64 slotId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<AttributeValue>> ProductManager.GetAttributeValues(Int64 recordId, Int64 channelId, Int64 catalogId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductRelationType>> ProductManager.GetRelationTypes(Int64 recordId, Int64 channelId, Int64 catalogId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductSearchResult>> ProductManager.GetRelatedProducts(Int64 recordId, Int64 channelId, Int64 catalogId, Int64 relationTypeId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductRefiner>> ProductManager.GetRefiners(ProductSearchCriteria productSearchCriteria, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductAvailableQuantity>> ProductManager.GetProductAvailabilities(IEnumerable<Int64> itemIds, Int64 channelId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductPrice>> ProductManager.GetActivePrices(ProjectionDomain projectDomain, IEnumerable<Int64> productIds, DateTimeOffset activeDate, String customerId, IEnumerable<AffiliationLoyaltyTier> affiliationLoyaltyTiers, QueryResultSettings queryResultSettings)
  • Task<PagedResult<MediaLocation>> ProductManager.GetMediaLocations(Int64 recordId, Int64 channelId, Int64 catalogId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<MediaBlob>> ProductManager.GetMediaBlobs(Int64 recordId, Int64 channelId, Int64 catalogId, QueryResultSettings queryResultSettings)

SalesOrderManager APIs

  • Task<PagedResult<SalesOrder>> SalesOrderManager.Search(SalesOrderSearchCriteria salesOrderSearchCriteria, QueryResultSettings queryResultSettings)

APIs that are available for an anonymous role

CartManager APIs

  • Task<SalesOrder> CartManager.Checkout(String id, String receiptEmail, TokenizedPaymentCard tokenizedPaymentCard, String receiptNumberSequence, IEnumerable<CartTenderLine> cartTenderLines)
  • Task<Cart> CartManager.Copy(String id, Int32 targetCartType)
  • Task<Cart> CartManager.AddCartLines(String id, IEnumerable<CartLine> cartLines)
  • Task<Cart> CartManager.UpdateCartLines(String id, IEnumerable<CartLine> cartLines)
  • Task<CartDeliveryPreferences> CartManager.GetDeliveryPreferences(String id)
  • Task<PagedResult<SalesLineDeliveryOption>> CartManager.GetLineDeliveryOptions(String id, IEnumerable<String> cartLineIds, Address shippingAddress, QueryResultSettings queryResultSettings)
  • Task<PagedResult<DeliveryOption>> CartManager.GetDeliveryOptions(String id, Address shippingAddress, QueryResultSettings queryResultSettings)
  • Task<Cart> CartManager.UpdateLineDeliverySpecifications(String id, IEnumerable<LineDeliverySpecification> lineDeliverySpecifications)
  • Task<Cart> CartManager.UpdateDeliverySpecification(String id, DeliverySpecification deliverySpecification)
  • Task<PagedResult<Product>> CartManager.GetProductsInCart(String id, QueryResultSettings queryResultSettings)
  • Task<CartPromotions> CartManager.GetPromotions(String id)
  • Task<Cart> CartManager.AddDiscountCode(String id, String discountCode)
  • Task<Cart> CartManager.RemoveDiscountCodes(String id, IEnumerable<String> discountCodes)
  • Task<Cart> CartManager.RemoveCartLines(String id, IEnumerable<String> cartLineIds)
  • Task<CardPaymentAcceptPoint> CartManager.GetCardPaymentAcceptPoint(String id, CardPaymentAcceptSettings cardPaymentAcceptSettings)
  • Task<CardPaymentAcceptResult> CartManager.RetrieveCardPaymentAcceptResult(String resultAccessCode)
  • Task<Cart> CartManager.Read(String id, ICollection<String> expandProperties)
  • Task<Cart> CartManager.Update(Cart entity)
  • Task<Cart> CartManager.Create(Cart entity)

CatalogManager and ProductCatalogManager APIs

  • Task<PagedResult<ProductCatalog>> ProductCatalogManager.GetCatalogs(Int64 channelId, Boolean activeOnly, QueryResultSettings queryResultSettings)
  • Task<PagedResult<Category>> CategoryManager.ReadAll(QueryResultSettings queryResultSettings, ICollection<String> expandProperties)
  • Task<PagedResult<Category>> CategoryManager.GetCategories(Int64 channelId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<Category>> CategoryManager.GetChildren(Int64 channelId, Int64 categoryId, QueryResultSettings queryResultSettings)

StoreOperationsManager and OrgUnitManager APIs

  • Task<PagedResult<CardTypeInfo>> StoreOperationsManager.GetCardTypes(QueryResultSettings queryResultSettings)
  • Task<PagedResult<String>> StoreOperationsManager.GetSupportedPaymentCardTypes(QueryResultSettings queryResultSettings)
  • Task<PagedResult<CountryRegionInfo>> StoreOperationsManager.GetCountryRegionsByLanguageId(String languageId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<DeliveryOption>> StoreOperationsManager.GetDeliveryOptions(QueryResultSettings queryResultSettings)
  • Task<GiftCard> StoreOperationsManager.GetGiftCard(String giftCardId)
  • Task<LinkToExistingCustomerResult> StoreOperationsManager.InitiateLinkToExistingCustomer(String email, String activationToken, String emailTemplateId, IEnumerable<NameValuePair> emailProperties)
  • Task<LinkToExistingCustomerResult> StoreOperationsManager.FinalizeLinkToExistingCustomer(String email, String activationToken)
  • Task<ValidateHardwareStationTokenResult> StoreOperationsManager.ValidateHardwareStationToken(String deviceNumber, String hardwareStationToken)
  • Task<PagedResult<StateProvinceInfo>> StoreOperationsManager.GetStateProvinces(String countryRegionId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<TenderType>> StoreOperationsManager.GetTenderTypes(QueryResultSettings queryResultSettings)
  • Task<PagedResult<OrgUnit>> OrgUnitManager.ReadAll(QueryResultSettings queryResultSettings, ICollection<String> expandProperties)
  • Task<PagedResult<OrgUnitLocation>> OrgUnitManager.GetOrgUnitLocationsByArea(SearchArea searchArea, QueryResultSettings queryResultSettings)
  • Task<PagedResult<OrgUnitAvailability>> OrgUnitManager.GetAvailableInventory(String itemId, String variantId, String barcode, QueryResultSettings queryResultSettings)
  • Task<PagedResult<OrgUnitAvailability>> OrgUnitManager.GetAvailableInventoryNearby(IEnumerable<ItemUnit> itemIds, SearchArea searchArea, QueryResultSettings queryResultSettings)
  • Task<TillLayout> OrgUnitManager.GetTillLayout()
  • Task<ChannelConfiguration> OrgUnitManager.GetOrgUnitConfiguration()
  • Task<PagedResult<OrgUnit>> OrgUnitManager.Search(SearchStoreCriteria storeSearchCriteria, QueryResultSettings queryResultSettings)
  • Task<OrgUnit> OrgUnitManager.Read(String orgUnitNumber, ICollection<String> expandProperties)

CustomerManager APIs

  • Task<Customer> CustomerManager.Create(Customer entity)

ProductManager APIs

  • Task<PagedResult<ProductSearchResult>> ProductManager.SearchByCategory(Int64 channelId, Int64 catalogId, Int64 categoryId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductSearchResult>> ProductManager.SearchByText(Int64 channelId, Int64 catalogId, String searchText, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductRefiner>> ProductManager.GetRefinersByCategory(Int64 catalogId, Int64 categoryId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductRefiner>> ProductManager.GetRefinersByText(Int64 catalogId, String searchText, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductRefinerValue>> ProductManager.GetRefinerValuesByCategory(Int64 catalogId, Int64 categoryId, Int64 refinerId, Int32 refinerSourceValue, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductRefinerValue>> ProductManager.GetRefinerValuesByText(Int64 catalogId, String searchText, Int64 refinerId, Int32 refinerSourceValue, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductSearchResult>> ProductManager.RefineSearchByCategory(Int64 channelId, Int64 catalogId, Int64 categoryId, IEnumerable<ProductRefinerValue> refinementCriteria, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductSearchResult>> ProductManager.RefineSearchByText(Int64 channelId, Int64 catalogId, String searchText, IEnumerable<ProductRefinerValue> refinementCriteria, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductDimensionValue>> ProductManager.GetDimensionValues(Int64 recordId, Int64 channelId, Int32 dimension, IEnumerable<ProductDimensionValue> matchingDimensionValues, QueryResultSettings queryResultSettings)
  • Task<PagedResult<SimpleProduct>> ProductManager.GetVariantsByDimensionValues(Int64 recordId, Int64 channelId, IEnumerable<ProductDimensionValue> matchingDimensionValues, QueryResultSettings queryResultSettings)
  • Task<PagedResult<SimpleProduct>> ProductManager.GetVariantsByComponentsInSlots(Int64 recordId, Int64 channelId, IEnumerable<ComponentInSlotRelation> matchingSlotToComponentRelationship, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductComponent>> ProductManager.GetDefaultComponents(Int64 recordId, Int64 channelId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductComponent>> ProductManager.GetSlotComponents(Int64 recordId, Int64 channelId, Int64 slotId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<AttributeValue>> ProductManager.GetAttributeValues(Int64 recordId, Int64 channelId, Int64 catalogId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductRelationType>> ProductManager.GetRelationTypes(Int64 recordId, Int64 channelId, Int64 catalogId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductSearchResult>> ProductManager.GetRelatedProducts(Int64 recordId, Int64 channelId, Int64 catalogId, Int64 relationTypeId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductRefiner>> ProductManager.GetRefiners(ProductSearchCriteria productSearchCriteria, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductAvailableQuantity>> ProductManager.GetProductAvailabilities(IEnumerable<Int64> itemIds, Int64 channelId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<ProductPrice>> ProductManager.GetActivePrices(ProjectionDomain projectDomain, IEnumerable<Int64> productIds, DateTimeOffset activeDate, String customerId, IEnumerable<AffiliationLoyaltyTier> affiliationLoyaltyTiers, QueryResultSettings queryResultSettings)
  • Task<PagedResult<MediaLocation>> ProductManager.GetMediaLocations(Int64 recordId, Int64 channelId, Int64 catalogId, QueryResultSettings queryResultSettings)
  • Task<PagedResult<MediaBlob>> ProductManager.GetMediaBlobs(Int64 recordId, Int64 channelId, Int64 catalogId, QueryResultSettings queryResultSettings)