Digital Commerce API Usage Considerations

Consider the points in this section when making design and deployment decisions.

  • Ensure that you delete logger trace flags and disable all logging services, such as CacheAPI.EcommLogger and the pricing log in CPQ Configuration settings.

  • Cacheable APIs do not currently support penalties that are invoked when attempting to remove promotions from an active asset. To learn more about penalties, see Create a Penalty Rule.

  • Attribute binding is not supported by Digital Commerce APIs. See Create a Pricing Element Adjustment in the Product Console

  • The deltaPrice, deltaValidate, and levelBasedApproach custom settings are not supported when using the Digital Commerce APIs. If deltaPrice or deltaValidate are enabled, line items that are added to the cart will not be priced or validated correctly. If levelBasedApproach is enabled, Digital Commerce API calls return only a partial response. In addition, subsequent API calls will not be able to perform any further operations on an existing basket.

  • For releases prior to CME Winter '20: Vlocity Communications API Caching does not honor product selling period or effectivity dates. The following dates in the product catalog are ignored by Vlocity Communications API caching: Selling Start Date, Selling End Date, Fulfillment Start Date, End Of Life Date, Effective Date and Effective End.

    Starting with the CME Winter '20 release, these product selling period and effectivity dates are supported; however, effectivity dates for rules are not supported.

  • Cacheable context dimensions do not support comparisons operations; only absolute values. For example, a context dimension that specifies "Postal Code Range must be greater than {numeric value}" is not supported. Therefore, it is advisable to convert these dimensions to Boolean values. For additional complex dimensions, contact our Product Management team.

  • Cache management will require manual steps while the admin capabilities are expanded.

  • The off-platform solution will be designed to be gateway agnostic, but the first iteration will be optimized on AWS.

  • When creating a promotion override, excluding a child product from the promotion is not supported.

  • For releases prior to CME Summer '20: When creating catalog product relationships, do not enter both products and promotions in the same product relationship record. For example, do not create a record for a product and then add a promotion to the same record. You should instead create one record for the product and one record for the promotion.

  • Ensure there are no blank spaces in code fields in objects that are used in the Cacheable API configuration.

  • Run all appropriate CMT Administration jobs (such as Field Maps Maintenance, Product Hierarchy Maintenance, and so on) before running the cache API jobs.

  • Starting with the Winter '20 release, the Digital Commerce APIs support JSONAttribute v2.

  • Consider removing old pseudo records. See Delete Pseudo Records.

  • For the Winter '20 release, the custom setting UseAssetReferenceIdForParentAndRoot=True is not supported for the Digital Commerce APIs. Set UseAssetReferenceIdForParentAndRoot=false instead.

  • The GetOffers API accepts only one context parameter value in the API call. For example, context={"AccountSla"="Gold"} would be supported, but context={"AccountSla"="Gold,Silver"} would not be supported.

  • The Get Offers by Catalog API returns override values of attributes only for products that are part of a promotion. Because the API returns only root-level products and does not return child products, it does not return overrides except in the case of products within a promotion.

  • Be aware that availability and eligibility interface implementations are ignored while generating the cache. Cache generation defaults to executing eligibility context rules by leveraging context dimensions for Digital Commerce APIs. However, CPQCart leverages Cart-Based APIs which also support eligibility context rules that could be set without affecting cache generation. Therefore, Digital Commerce API cache generation ignores the following:

    • ProductAvailabilityInterface

    • ProductAvailabilityOpenInterface

    • ProductEligibilityInterface

    • ProductEligibilityOpenInterface

    • As of the Fall ’20 release, after invoking the Populate API batch job, the following are honored: Active flag, Orderable flag, Effectivity dates, selling start and end dates on offers (Products or Promotions). If an offer becomes ineligible later, due to a selling end date or  effectivity date expiration, it will not be automatically removed from the response.

    • To remove an inactive offer from a getOffers API response, clear the cached API response records and rerun the Populate API cache batch job. Then, manually edit the offer entry in the Product Console to trigger cache management and run the regenerate cache batch job.

    • For CME Fall '18 release, ensure that you clear the cache before running the GetOffers batch job.

    Custom Settings (Fall '18):

    • CacheAPI.GetOffersCacheRecLimit:

      • DefaultValue: 9000

      • Suggested Value: 5000

      • Applicable On: GetOffers and GetContainsOffers batch jobs

        This custom setting represents the maximum number of results that can be cached for each catalog during the Populate API cache batch jobs for GetOffers or GetContainsOffers. Clear the cache before running the GetOffers batch job. (CME Fall '18).

      • API calls are cached during run time as part of incremental cache population.

  • The following custom settings are not supported: DeltaPrice, DeltaValidate, and LevelBasedApproach.

  • As of the Fall ’20 release, after invoking the Populate API batch job, the following are honored: Active flag, Orderable flag, Effectivity dates, selling start and end dates on offers (Products or Promotions). If an offer becomes ineligible due to a selling end date or effectivity date expiration, the offer will not be automatically removed from the response.

  • To remove expired offer details from the Digital Commerce cache, clear the cached API response records and rerun the Populate API Cache batch job. Then, manually edit the offer entry in the Product Console to trigger the cache management and run the regenerate batch job.

  • Note the following about pricing when running this API:

    • When Get Offer Details is called initially, the pricing interface is not executed.

    • When Get Offer Details is called with context parameters, the correct pricing is returned based on context eligibility (tightest match) of the prices. The pricing interface is not executed.

    • The GetOfferDetails API triggers the pricing interface implementation only when a change to the offer occurs. For example, the pricing interface implementation is triggered when a user modifies the QTY amount or modifies an attribute value. Therefore, when GetOfferDetails is initially called, the pricing interface implementation is not executed. If specific context key elements are passed, correct pricing is returned based on the response when running API caching rules, which recognize the pricing interface implementation.

  • As of the Fall ’20 release, after invoking the Populate API batch job, the following are honored: Active flag, Orderable flag, Effectivity dates, selling start and end dates on offers (Products or Promotions). If an offer becomes ineligible due to a selling end date or effectivity date expiration, the offer will not be automatically removed from the response.

  • To remove expired offer details from the Digital Commerce cache, clear the cached API response records and rerun the Populate API Cache batch job. Then, manually edit the offer entry in the Product Console to trigger cache management and run the regenerate cache batch job.

  • The GetContainsProducts API accepts only one context parameter value in the API call. For example, context={"AccountSla"="Gold"} would be supported, but context={"AccountSla"="Gold,Silver"} would not be supported.

  • The sortBy parameter and sorting are not supported in the CME Fall '18 release of this API.

  • Because products are not added to the cart, validation and pricing rules do not run; therefore, product relationship type rules are not supported.

  • The DeltaPrice, DeltaValidate, and LevelBasedApproach are not supported.

  • In addition to the offers returned by the API, Get Contains Products also returns the offer itself.

  • Custom Settings (as of CME Fall '18): CacheAPI.GetOffersCacheRecLimit

    • DefaultValue: 9000

    • Suggested Value: 5000

    • Applicable to GetOffers and GetContainsOffers batch jobs

    • This custom setting represents the maximum number of results that can be cached for each catalog during CachePopulation batch job for GetOffers or GetContainsOffers.

    • Ensure that you clear the cache before running the GetOffers batch job (CME Fall '18).

  • The deltaPrice, deltaValidate, levelBasedApproach custom settings are not supported.

  • One-time charges and monthly charges (NRC and MRC) must be defined for each product. If NRC or MRC are not available, set them to $0.00.

  • The Configure Offer API uses the Pricing Interface Implementation; therefore Attribute-Based Pricing via Price Plans is supported.

  • The Post Offer Details with Configuration API is specific to the orderable Bundled Products that are being configured. Post Offer Details with Configuration APIs do not honor Advanced Rules that are defined to evaluate across multiple bundles.

  • For releases prior to CME Summer '19: Deleting any offer of type promotion or an offer that has been affected by any rules due to a promotion from the basket will render the basket invalid. The user must start with a fresh basket after such an operation, which can be handled by custom code.

  • For releases prior to CME Summer '19: Only add and delete were supported, not update. Deleting from the basket, configuring a new offer, and adding to the basket would effectively update the basket.

  • The Basket API supports Multi-Transaction Service.

  • deltaPrice, deltaValidate, and levelBasedApproach are not supported

  • For releases prior to CME Winter '20: Cloned child line items are not supported. Cloned child line items are supported as of the Winter '20 release.

  • For releases prior to CME Winter '20: Adding the same promotion multiple times to a single basket is not supported. This functionality is supported as of the Winter '20 release.

  • When you create the basket with price=false and validate=true, cartContextKey is computed with no pricing done on the cart. When you call a getBasket on the created basket with price=true and validate=false, the basket shape changes as pricing is done on the cart. Therefore, cartContextKey is recomputed.

The Asset To Basket API does not support nesting of multiple baskets from the same asset with different request dates.

Example: Assume you create an asset to basket order with a request date of August 1st 2020 and make modifications. Next, another asset to basket order is created with request date of September 1st 2020; the latest request will not have the changes made to the basket that was created on August 1st.

Example: Suppose you create an asset to basket order with a request date of August 1st, make modifications, and convert the basket to a cart using the Create Cart from Basket API. Next, you create another asset to basket order with a request date of September 1st; the basket will have the changes that were created on August 1st.

The createCart API does not currently accept the order start date as a parameter. The cart is always created on the date of the createCart API call.

  • Only pricing-element prices are supported. A one-time charge and a recurring charge must be defined for each product as a base price. Zero-base prices are allowed.

  • Only one-time charge/total and recurring charge/total are supported in the Fall 2018 release. Therefore, loyalty and other pricing variables are not supported.

  • Prices shown in the GetOffers, GetOfferDetails, GetContainsProducts are read directly from the defined price list entries for each product and promotion in the catalog.

    Starting from CME Spring ‘22, Digital Commerce supports all the features of Usage Pricing that are supported by Industries CPQ, including:

    • Promotions

    • Attribute Binding

    • Attribute-Based Pricing

    • Roll-up price

    • Price overrides

    For more information on Usage-Based Pricing, see

  • For releases prior to CME Winter '20: Time plan and time policy are not honored in the price result. Time plan and time policy are supported as the Winter '20 release.

  • The GetOffers, GetOfferDetails, and GetContainsProducts APIs do not have a cart context; therefore, promotion discounts that are defined on a promotion product that is not a top-level offer, but that references a parent offer in its price list entry definition, will not be calculated. This type of promotion discount can be calculated only when a cart exists with the parent offer already added to it.

    An example of the above scenario would be to define a promotion, add a promotion Product A, then under product adjustments, add a 10% monthly recurring charge (MRC) discount for Product A with a Parent Offer Context pointing to an offer Product B. This promotion means Product A's MRC price is 10% less if Product B exists and Product A is under Product B's hierarchy in the cart.

  • To Cache Eligibility Combinations, ensure you enable cacheable mode, and have populated values for caching and default values for context dimensions. Otherwise, API performance will be negatively impacted and result in frequent cache misses and might lead to caching of unwanted combinations.

  • The context scope associated with the cacheable dimension must be of type Entity (Virtual and Session are not supported).

  • Cacheable dimension does not support any dynamic fields. (Domain Type must be of type "Type In" => SObject and picklist is not supported because there will not be any cross-validation while generating combinations against the picklist values).

  • The context parameter in all of the above APIs is case sensitive. Otherwise, eligibility results might not be accurate.

  • All the rules defined for generation of eligibility combination must have Rule Type as Qualification and Rule purpose as Eligibility.

  • The rule condition supports only == and != operators in the case of Eligibility Context Rules. The != operator is supported only for known users, while the == operator is supported for anonymous users as well as known users.

  • Rules support only AND or OR Expression Modes in rule condition evaluation.

  • Rule Set supports only AND or OR Expression Mode rules evaluation. Custom expression modes are not supported.

  • Fail Level and Fail Message are not honored.

  • For any configuration changes related to context dimension, rules, rule conditions, rule sets, or rule set assignments to products or promotions, first clear the platform cache, then run the ContextEligibilityGenerator batch job and the rest of the batch jobs under Populate API Cache in the Vlocity CMT Administration screen.

  • Prior to the Summer '19 release, header rules within context rules are ignored for Digital Commerce anonymous APIs.

  • Eligibility Rules are applicable in GetOffers API and GetContainsProducts API only.

  • Beginning with the Fall 2018 release, the Context Dimension Name and Code must be identical.

  • Custom Settings (CME Fall '18): The CacheAPI.CombinationLimit custom setting represents the maximum number of results that can be cached for each catalog during ContextEligibilityGenerator CachePopulation batch job.

    • DefaultValue: 9000

    • Suggested Value: 5000

  • Even though scope and mappings are defined for context dimension, Pricing Rules will obtain values from the context parameter of the URL to evaluate the rule conditions.

  • Pricing context rules are supported in Basket API, Configure API, and Create CART API.

  • The Cart-Based defined scope for a context Dimension, which acted as input for rules. For example, consider the following scenario:

    • Create a Dimension: AccountSla, Scope: Account, Mapping: {SourceExpression: Account.Sla__c}

    • Create a Rule named R1 which says: AccountSla == gold, and create a rule set called RS1.

    • Assign this ruleset to PriceListEntry (PLE1 => One time charge: 50) of product P1 to RS1. Assume one more PLE for P1 (PLE2, one-time charge: 40).

    • Now assume you are trying to add P1 in a Cart-Based API CPQ cart while adding product P1. This API attempts to fetch the best possible match of the prices assigned to product P1 based on the context rules assigned.

    • Because PLE1 is assigned to RS1, it fetches the AccountSla value from the scope object that was assigned to it.

    • Assume that AccountSla value is gold in the Account object that is related to the current cart, then the existing context rule service will replace AccountSla in the ( AccountSla == gold) condition with the AccountSla value (which is obtained from the related account object) and the final expression of the rule condition will be simplified to (gold == gold). Because this qualifies PLE1, PLE1 takes priority over PLE2 based on the weight defined in the dimension.

    • Based on the above scenario, the input source for the rule condition was given from the Scope objects.

  • In the Digital Commerce APIs, context scope, mappings, rules, rule conditions, and rulesets must be defined as specified above. But instead of using the scope object for the input source to evaluate the rule conditions, the API uses the context parameter provided in the URL to evaluate the rule conditions.

    To illustrate the above scenario, consider the following URL:

    /v3/catalogs/Mobiles/basket/5b7f58ae49f221537c97e7fd4f6d063c?context={"AccountSla":"Silver"}

    • Assume the URL above is used to add product P1 to the basket. The URL has a context with AccountSla as key, which is the code of the dimension that was defined.

      Because silver is not equal to gold, the rule fails and PLE2 takes precedence over PLE1.

      Because silver is not equal to gold, the rule fails and PLE2 takes precedence over PLE1.

      The evaluated rule condition expression is as follows: ("Silver" == "Gold")

  • This feature is supported only by Basket API, Configure API, and Create CART API

  • The Create Cart from Basket API requires that catalogCode be sent as an input to the API call. The catalogCode is required to determine the PriceList to use for the cart. If you have a single catalog, then specify the catalogCode in the input of the Create Cart API. If you have multiple catalogs, use the same price list on all of the catalogs. Using one price list allows you to specify any one of the catalog codes in the input of createCart API.

  • When creating a cart using the Digital Commerce APIs, the order start date will be the date on which the Create Cart from Basket API was called.

  • When using the Create Cart API, effectivity and eligibility checks are supported only when the cartContextKey parameter is set. Effectivity and eligibility checks are not supported by setting the JSONResult parameter.

  • The Digital Commerce Cache Manager is unable to regenerate or recompute existing baskets if they contain configured offers. If a basket contains configured offers and changes are made to the catalog, the cache manager invalidates the baskets.

  • The Cache Manager is unable to regenerate or recompute responses to the Post Offer Details with Configuration API call. If a basket contains configured offers and changes are made to the catalog, information returned by the Post Offer Details with Configuration API is invalid.

  • The Cache Manager does not support scenarios in which a child product within the catalog hierarchy is changed to inactive.

  • The Cache Manager does not support scenarios in which a promotion is active but the promotional product is inactive.

For best performance, whether the user is known or anonymous, call the API with both the context parameter and the context key. This is a two-step process.

For example, first issue a request to the Get Offers by Catalog API. The contextKey is returned in the output of the API call, as shown here:

Subsequent requests are then made using the contextKey and the context. For example:

If the context shape changes (changes are made to the account, an asset that belongs to the account, or to a contract), the context key must be regenerated.