Offers APIs

The Digital Commerce APIs are optimized for consumer shopping use cases where the user may be anonymous until well into the check-out process. These APIs are also optimized to enable caching of API responses to provide performance enhancements and scalability. These APIs are also optimized for lower bandwidth connections between the client app and the server by minimizing the metadata returned in the response.

The Digital Commerce APIs are provided in addition to the Industries Cart-based APIs. The Cart-based APIs are optimized for highly interactive cart operations by contact center agents and sales reps using an editor such as the Industries Cart UI. Therefore, Cart-based APIs provide more metadata to the client browser enabling a wide array of operations. Both the Cart-based CPQ APIs and the Digital Commerce APIs are supported and actively enhanced.

The Digital Commerce APIs are not intended to replace the Cart-based APIs. All the Vlocity Omnichannel REST APIs simplify client app development by hiding the details of internal CPQ processing. Client-side developers do not need to understand details of the underlying CPQ logic or need to know the proper order to apply eligibility and availability rules.

The GetOffers API returns the list of qualified offers in a catalog for the passed context input.

The response behavior for the logged-in user and anonymous users is different. For anonymous users, only the qualified offers are returned in the response. For logged-in users, all the offers are returned but with a qualification node on it stating whether the offer is qualified or not qualified for the context shape derived from the account and contract ID passed in the input request URL.

The cache warmup batch jobs only populate the qualified list data for the anonymous users for the generated context combinations by taking the values for caching for the context dimensions having the cacheable mode set as true.

The batch jobs also consider the context values defined in the rule conditions. If a context value is passed that has not been cached or the request is first made for a logged-in user having a context key that has not yet been encountered, a cache miss scenario occurs and the response is generated at run-time and cached.

The cache miss scenario uses the time-sliced catalog data profile currently effective in the cache. That profile contains the list of exact offer versions under the currently effective catalog. The context eligibility maps are calculated and the prices and offers profile are stitched together. The data is cached with the effectiveness of that time slice.

A cache hit scenario where the cacheKey is found in the cache includes the currently active version. Even though the cache key is the same, the version effectivity is different because of the different effective start and end time of the cache entry. At any given point in time, only one version of the cache is effective, with no overlaps, so there is no change in the computation of the cache key.

The priceResults and offers profile for the offers are populated by the cache initialization batch jobs. At run-time, the batch jobs only stitch the already cached data and calculate only the eligibility maps or qualified list. Only the offers with a lifecycle status of Released are present in the response.

The GetContainsOffers API finds the offers that contain a particular product in its hierarchy.

For the cache miss scenario, the time slice information is fetched based on the current date. For that particular time slice, the containsOffer information is populated, cached, and returned. The response contains the offer with the version of the product for the time slice based on the current date.

The GetOfferDetails API gets the details of an offer (product or promotion) from a specified catalog. The offer details generated are the complete details of the product and its hierarchy (if the offer is a product) or the details of the promotion and its promotional items along with the full hierarchy of the promotional item. The response contains detailed information about all the child products.

For anonymous users, the default pricing defined at admin-time is considered. For logged-in users, the tightest match prices are computed and added in the response. The prices are cached separately and are stitched to the root and child products at runtime using price keys as the slot.

Price keys are generated using the product, promotion, offer, and price list IDs. These are also used when generating price keys during getPrices batch job.

For anonymous users, the price results are agnostic of the context of the user and consist of only the base prices and adjustments without honouring any qualifying context rules association. For logged-in users, weights and qualifying rules on the PLEs are honoured and price results are computed and cached.

The cache key is generated using the offer code and the user context. The cache entry is checked for validity in the current time frame for that cache key. If the cache key is found, it becomes a cache hit scenario and price details are added at runtime. If price results for an offer in the hierarchy are not found, an error occurs and states that no price results were found.

For a logged-in user, the cache miss for offer details is processed using the hierarchyResult as the list of child products. If the price results are not found in the cache at run time, then they are generated and cached separately. The tightest match pricing runs with the reference date time as the current time. Price list entries and rules that are valid in the current time frame are considered in the pricing. Offer details are cached with the same effectivity as the current time slice effectivity.

The current offer version is derived from the offer version details already cached by the version info generator batch job. The current hierarchy is cached as generated by the hierarchy result batch jobs. The cache miss for offer details applies to all the offers in the hierarchy for the parent.

The configureOffer API lets a user configure a product bundle before adding items to the basket. In a single transaction, users can update the quantity, change attributes, and add a child product by changing the quantity. All the advanced rules, pricing rules, matrix-based pricing, etc. work in the configure API to generate the response. The input to the API is the offerDetails response for that offer and the updated quantity or attributes.

With versioning enabled for an offer code in different frames of time, there can be different versions of the offer details. Therefore, the validation services check whether the current offerVersion configuration in the input is valid in the current time frame.

To check for the version effectivity in the response of the getOfferDetails, time slice information is attached that mainly includes time slice effectivity start time, time slice effectivity, and end time to determine the effectivity of the input configuration. The validation service also checks cardinality and version. The system creates the XLIs using the offer details configuration that was passed. Validation and pricing run with the reference dates as the current date-time. The generated response is cached with the effectivity of the time slice of that offer detail.