Work with the Pricing API

Abstract

How to use the Sitecore XC Pricing API to integrate pricing-related operations with other business systems using C# programming.

This topic provides information, including examples, on how to use the Sitecore XC Pricing API to integrate pricing-related operations with other business systems, using C# programming.

You must include Commerce Engine operations and commands within a container call (using C#) as shown in this example.

To execute any operation in the Sitecore Experience Commerce (XC) system, the calling system must first obtain valid bearer authorization token from the Sitecore Identity Server.

The Pricing API provides methods to add, get, edit and manage associated catalogs for price books.

A price book is a container for a set of pricing information.

The Pricing API provides the following methods to add, get, edit and manage associated catalogs for price books:

Add price book (C#)

To add a price book, you must specify a unique price book name in your query. Optionally, you can also include a display name and a description.

To add a price book, for example, specifying an internal name (MyPriceBook), a display name (Book Display Name), and a book description (Book Description):

DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.AddPriceBook("MyPriceBook", "Book Display Name", "Book Description", "{0F65742E-317F-44B0-A4DE-EBF06209E8EE}");
CommerceCommand command = Proxy.DoCommand(actionQuery);

The query response returns the price book friendly id using the PriceCardAdded model, for example:

PriceBookAdded priceBookAddedModel = command.Models.OfType<PriceBookAdded>().FirstOrDefault();
string bookFriendlyId = priceBookAddedModel?.PriceBookFriendlyId;

Get price book (C#)

You can retrieve an existing price book programmatically by including its friendly ID in the query. Optionally, you use the OData expand option to expand the Odata query to include price book's components.

To retrieve a price book, for example, with its component:

DataServiceQuerySingle<PriceBook> query = container.PriceBooks.ByKey(bookFriendlyId).Expand("Components");
PriceBook book = Proxy.GetValue(query);

Edit a price book (C#)

You can edit a price book programmatically using the Pricing API. When you edit a price book, you cannot change its internal name. You can modify the price book's display name, description and the currency set properties.

Note

To change the currency, you can use the Commerce Control Panel located in the Sitecore Content Editor.

To edit a price book:

  • To change the price book's description and display name:

    DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.EditPriceBook(bookFriendlyId, "edited book description", "edited book display name", "{0F65742E-317F-44B0-A4DE-EBF06209E8EE}");
    CommerceCommand command = Proxy.DoCommand(actionQuery);
    
  • To change the price book description, for example, without changing its display name:

    actionQuery = container.EditPriceBook(bookFriendlyId, string.Empty, "edited book display name only", "{0F65742E-317F-44B0-A4DE-EBF06209E8EE}");
    command = Proxy.DoCommand(actionQuery);
    CommerceCommand command = Proxy.DoCommand(actionQuery);
    

Get associated catalogs (C#)

You use the Pricing API to retrieve the list of catalogs that are associated with a price book.

To get associated catalogs, for example, the list of catalogs associated with the AventureWorksPriceBook:

DataServiceQuery<AssociatedCatalogModel> query = container.GetPriceBookAssociatedCatalogs("AdventureWorksPriceBook");
List<AssociatedCatalogModel> catalogs = Proxy.Execute(query).ToList();

Associate a catalog to a price book (C#)

You can associate one or multiple catalogs to a price book programmatically. A catalog can only be associated with one price book.

Note

A catalog can only be associated to a single price book at a time. If a catalog is already associated with a price book, you can associate that catalog with a different price book, but the associations with the first catalog is lost. Only the latest association remains.

To associate a catalog to a price book, for example, to associate MyPriceBook to MyCatalog:

DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.AssociateCatalogToPriceBook("MyPriceBook", "MyCatalog");
CommerceCommand command = Proxy.DoCommand(actionQuery);

Disassociate a catalog from a price book (C#)

You can a catalog from the associated price book programmatically.

To disassociate a catalog from a price book, for example to disassociate MyCatalog" from MyPriceBook:

DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.DisassociateCatalogFromPriceBook("MyPriceBook", "MyCatalog");
CommerceCommand command = Proxy.DoCommand(actionQuery);

The Pricing API provides the following methods to perform add, get, edit, duplicate and delete actions for price cards:

To add a price card to a price book, you must specify the internal name of the price card in your query and the price book name to which to add the card.

The name of the price card must be unique within the price book. You cannot change the internal name of a price card after you create it. Optionally, you can also include a price card display name and a description.

To add price card to a price book, for example, to add MyPriceCard to MyPriceBook:

DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.AddPriceCard("MyPriceBook", "MyPriceCard", "Card Display Name", "Card Description");
CommerceCommand command = Proxy.DoCommand(actionQuery);

// the price card friendly id is returned in the PriceCardAdded model
PriceCardAdded priceCardAddedModel = command.Models.OfType<PriceCardAdded>().FirstOrDefault();
string cardFriendlyId = priceCardAddedModel?.PriceCardFriendlyId;

The query returns the friendly id the price card using the PriceCardAdded model, show in the following example:

PriceCardAdded priceCardAddedModel = command.Models.OfType<PriceCardAdded>().FirstOrDefault();
string cardFriendlyId = priceCardAddedModel?.PriceCardFriendlyId;

You can modify the details of a price card programmatically. The price card's internal name cannot change. You can only modify the price card's display name and its description. If your query does not specify a new value for a property, then existing values remain unchanged.

To edit a price card, include the new name or the new description or both in your query, for example:

DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.EditPriceCard(cardFriendlyId, "edited card display name", "edited card description");
CommerceCommand command = Proxy.DoCommand(actionQuery);

Duplicate a price card when you want to create a new price card within the same price book, with all its price snapshots set to the draft status.

To duplicate a price card:

DataServiceActionQuerySingle<CommerceCommand> actionQuery  = container.DuplicatePriceCard(CardFriendlyId, "MyDuplicatePriceCard");
CommerceCommand command = Proxy.DoCommand(actionQuery);

The query returns the friendly ID of the new price card in the PriceCardAdded model, for example:

string duplicatedCardFriendlyId = command.Models.OfType<PriceCardAdded>().FirstOrDefault()?.PriceCardFriendlyId;

You can delete a price card only if it the it does not contain an approved snapshot.

To delete a price card:

DataServiceActionQuerySingle<CommerceCommand> actionQuery  = container.DeletePriceCard(cardFriendlyId);
CommerceCommand command = Proxy.DoCommand(actionQuery);

A snapshot contains a price that is defined to apply to a price card at a specified date and time. The Pricing API provides the following methods to perform add, edit, remove, add tag, remove tag and to set approval status for price snapshots:

Note

The status of a price card determines which operations you can perform.

You can only perform edit, remove, add tag, and remove tag operations on snapshots that are in a draft status.

Add a price snapshot (C#)

You can use the Pricing API to to add a snapshot to a price card programmatically.

In your query, specify the the price card friendly ID (cardFriendlyId, and the snapshotDate).

To add a snapshot to a price card, for example, using snapshotBeginDate = DateTimeOffset.UtcNow to make the pricing information applicable immediately (alternatively, you could specify a date in the future):

var snapshotBeginDate = DateTimeOffset.UtcNow;
DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.AddPriceSnapshot(cardFriendlyId, snapshotDate);
CommerceCommand command = Proxy.DoCommand();

The response returns the price snapshot id using the PriceCardAdded model:

string snapshotId = command.Models.OfType<PriceSnapshotAdded>;().FirstOrDefault()?.PriceSnapshotId;

Edit a snapshot (C#)

You can use the Pricing service API to edit a snapshot programmatically, for example, to change the date at which the price card applies.

You can only make change to price snapshots that are in the draft status.

To change a draft snapshot, for example, using the DateTimeOffset.UtcNow.AddDays(5) method:

var snapshotNewBeginDate = DateTimeOffset.UtcNow.AddDays(5);
DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.AddPriceSnapshot(cardFriendlyId, snapshotNewBeginDate);
CommerceCommand command = Proxy.DoCommand(actionQuery);

Remove a snapshot price (C#)

You can use the Pricing API to remove a snapshot price from a price card.

To remove the snapshot price:

DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.RemovePriceSnapshot(cardFriendlyId, snapshotId);
CommerceCommand command = Proxy.DoCommand(actionQuery);

Add a tag to a price snapshot (C#)

A tag is a way to group sellable items together. You can use the Pricing API to add a tag to a price snapshot. You can then use that tag to apply a snapshot to all sellable items assigned to the same tag.

To add a tag to a price snapshot, for example, MyTag:

DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.AddPriceSnapshotTag(cardFriendlyId, snapshotId, "MyTag");
CommerceCommand command = Proxy.DoCommand(actionQuery);

Removing a tag from a snapshot (C#)

You can remove a tag from a snapshot when you no longer want to apply the snapshot pricing to a group of sellable items with the same tag assigned.

To remove a tag from a snapshot, for example, to remove the tag MyTag from a specified snapshot ID:

DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.RemovePriceSnapshotTag(cardFriendlyId, snapshotId, "MyTag");
CommerceCommand command = Proxy.DoCommand(actionQuery);

You can use the Pricing API to define tiered pricing levels for different quantities of sellable items, for example, $5 for a single sellable item, but reducing the price to $4 if the customer buys five or more of the same sellable item.

The Pricing API provides methods to add, edit, and remove price tiers from a price snapshot:

Note

You can only perform these operations on price snapshots with a draft status.

Add a price tier (C#)

You can add tiered pricing to a price card using the Pricing API.

To add a tiered price to a price card, for example, add tier specifying USD currency, a quantity of 1 and price of 20:

DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.AddPriceTier(cardFriendlyId, snapshotId, "USD", 1, 20);
CommerceCommand command = Proxy.DoCommand(actionQuery);

The price tier id is returned in the PriceTierAdded model, for example:

string priceTierId = command.Models.OfType<PriceTierAdded>().FirstOrDefault()?.PriceTierId;

Edit a price tier (C#)

You can modify the price property of a tier price. You cannot change the quantity or currency.

To change the value of a tiered price, specify the the card friendly ID, snapshot ID and the price tier ID and the new amount value of the price tier in your request, for example:

DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.EditPriceTier(cardFriendlyId, snapshotId, priceTierId,30);
CommerceCommand command = Proxy.DoCommand(actionQuery);

Remove a price tier (C#)

You can use the remove the tiered price from a price card.

To remove a price tier from, specify the the card friendly ID, snapshot ID and the price tier ID in your request, for example:

DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.RemovePriceTier(cardFriendlyId, snapshotId, priceTierId);
CommerceCommand command = Proxy.DoCommand(actionQuery);

You can use the Pricing API to change a price snapshot status. Price snapshots are subject to the pricing approval process. During the approval flow, you can:

Change a snapshot status from draft to ReadyForApproval (C#)

Change a snapshot status from draft to ReadyForApproval to request approval. Optionally, you can include a comment in the request.

To request approval of a draft snapshot, for example, including a comment string (This snapshot is ready to be approved):

// requesting approval
DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.SetPriceSnapshotsApprovalStatus(cardFriendlyId, new List<string> { snapshotId }, "ReadyForApproval", "This snapshot is ready to be approved");
CommerceCommand command = Proxy.DoCommand(actionQuery);

Change a snapshot status from ReadyForApproval to draft (C#)

Change a snapshot status from ReadyForApproval to draft to reject a snapshot. Optionally, you can insert include a comment string in the query.

To change the status of a snapshot from ReadyForApproval to Draft, for example, including the optional comment string This snapshot has been rejected:

// rejecting approval of a snapshot
DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.SetPriceSnapshotsApprovalStatus(cardFriendlyId, new List<string> { snapshotId }, "Draft", "This snapshot has been rejected");
CommerceCommand command = Proxy.DoCommand(actionQuery);

Change a snapshot status to Approved (C#)

Change the status of a snapshot from ReadyForApproval to Approved to approve a snapshot. Optionally, you can include a comment string in the query.

To approve a snapshot:

// approving a snapshot
DataServiceActionQuerySingle<CommerceCommand> actionQuery = container.SetPriceSnapshotsApprovalStatus(cardFriendlyId, new List<string> { snapshotId }, "Approved", "This snapshot is now approved");
CommerceCommand command = Proxy.DoCommand(actionQuery);