Pricing API

16 min

introduction a price api is an interface that retrieves discounted prices for product variants based on promotions in the chord oms (order management system) it enables the front end to display real time prices from the chord oms instead of static prices from the chord cms (content management system) you can create and manage promotions in the chord oms, which are reflected instantly on the front end the price api evaluates specific types of promotions, automatically applying the highest discount to a product variant other types of promotions, such as coupon codes, are ignored prices on the front end may differ from checkout, but the oms always selects the best promotion for lower prices during checkout pricing api the pricing api returns the discounted price of a variant based on the configured promotions in the chord oms this allows the front end to display dynamic prices from the oms instead of static prices from the cms a typical use case would be a site wide promotion (ex , 10% off on everything for black friday) an operator can create the promotion in the oms, and the front end will reflect prices according to it without updating product content in the cms for performance and simplicity reasons, the pricing api only supports specific promotions only promotions that are automatically applied (i e , no coupon code) with either no rule or with the following rules are evaluated by the api product(s) variant(s) store order contains a subscription subscription creation order subscription interval greater single order (no subscription associated) if multiple promotions match the criteria (sku and interval), the api returns the price for the “best” promotion (ie, the highest discount) the api ignores all other promotions (coupon codes based on email, role, etc) technically, prices could be different during checkout since all promotions are evaluated during checking however, since the chord oms always selects the best promotion for the order, prices should always be lower in checkout than shown on the product detail page (pdp)and/or the product listing page (plp) caching the pricing api implements a cache to deliver discount pricing information quickly for rendering on a product page prices are cached using the following criteria variant quantity store interval length (optional) interval units (optional) cache busting there is no set expiration on cache lifetime once a discount price is calculated and cached, it will be retained indefinitely modifying a product's or variant's price or other attributes will not bust the cache the cache is busted (invalidated) in two circumstances a promotion created, modified, or removed a price for a product or variant is created or modified when any of the above actions occurs, the entire pricing cache is invalidated and will be rebuilt upon customer request api endpoint get /api/variants/{id|sku}/discount prices query parameters quantity (optional) the quantity that will be added to cart defaults to 1 interval length (optional) the subscription length interval units (optional) the subscription units (`day`, `week`, `month`, `year`) you can find the document for the api https //chord stoplight io/docs/chord oms/97bb142bb3669 get discount price example 1 chord oms > promotions > new promotion configure a promotion that apply to all orders, and provide 20% of per line item do not add any rules configure another promotion that apply to all orders, and provide 50% off on small alstroemeria ( alstroemeria small ) select variants in rules dropdown a request for alstroemeria small will return the following (50% off) curl 'https //plant staging assembly api com 	/api/variants/alstroemeria small/discount prices' { "id" 128, "sku" "alstroemeria small", "price" 5 0, "discount" 2 5, "discount price" 2 5, "promotion" { "id" 186, "name" "50% off of alstroemeria small" } } a request for carnations medium will return the following (20% off) curl 'https //plant staging assembly api com 	/api/variants/carnations medium/discount prices' { 	"id" 132, "sku" "carnations medium", "price" 10 0, "discount" 2 0, 	"discount price" 8 0, "promotion" 	 "id" 181, "name" "site wide" } } example 2 configured in the chord oms a 30% off on subscriptions with a 6 months interval and a 5% off on subscriptions with a 1 year interval a request for a subscription to carnations medium with a 6 months interval will return the following curl 'https //plant staging assembly api com 	/api/variants/carnations medium/discount prices? 	interval length=6& 	interval units=month' { "id" 132, "sku" "carnations medium", "price" 10 0, "discount" 3 0, "discount price" 7 0, "promotion" { "id" 187, "name" "30% off on subcriptions (6 months)" } } a request for a subscription to carnations medium with a 1 year interval will return the following curl 'https //plant staging assembly api com 	/api/variants/carnations medium/discount prices? 	interval length=1& 	interval units=year' { "id" 132, "sku" "carnations medium", "price" 10 0, "discount" 0 5, "discount price" 9 5, "promotion" { "id" 188, "name" "5% off on subscriptions (1 year)" } } a request for a one off purchase for carnations medium will return the following (no discount) curl 'https //plant staging assembly api com 	/api/variants/carnations medium/discount prices' { "id" 132, "sku" "carnations medium", "price" 10 0, "discount" 0 0, "discount price" 10 0, "promotion" null } frontend integration the frontend can use the usevariantprice hook (included in the nextjs starter autonomy package) to fetch the discounted price from the chord oms the hook hides the implementation details (api call, formatting, caching, etc) making the integration seamless from a frontend point of view usevariantprice the usevariantprice hook returns the discounted price of a variant based on the configured promotions in the chord oms if the variant is not discounted, it returns the regular price arguments argument type description input variantpriceinput this contains the parameters for the api call sku string the variant sku quantity? number the quantity that will be added to cart (useful for tier based promotions) intervallength? number the interval length required to fetch the price of a subscription intervalunits? string the interval units (day, week, month, year) required to fetch the price of a subscription price (optional) number if present, the function will return this as the variantprice in case of an api error typically, set as the cms price regularprice (optional) number if present, the function will return this as the regularvariantprice in case of an api error typically, set as the cms regularprice intervallength? number the interval length required to fetch the price of a subscription regularprice (optional) returns promise a promise that resolves when the discount price has been returned attributes type description variantprice number the discounted variant price returned by the oms regularvariantprice number the regular variant price returned by the oms formattedvariantprice string the formatted variant price according to the current locale ex $8 formattedregularvariantprice string the formatted regular variant price according to the current locale ex $8 isfetchingprice boolean a flag indicating if the request has completed example import { usevariantprice } from ' /hooks/actions' const { sku, price, regularprice } = currentvariant const { formattedvariantprice, formattedregularvariantprice, isfetchingprice, } = usevariantprice( { sku }, price, regularprice, ) return ( 	{!isfetchingprice && ( 	 <> 	 \<div><>{formattedregularvariantprice}\</div> 	 \<div><>{formattedvariantprice}\</div> 	 \</> 	)} ) / for a subscription, the interval also needs to be provided const { formattedvariantprice, formattedregularvariantprice, isfetchingprice, } = usevariantprice( { sku, intervallength, intervalunits, }, price, regularprice, ) / 💡 for existing frontend running on an old version of the nextjs starter autonomy , it might be impossible to integrate the usevariantprice hook an alternative is to use the lower level getprice function from the useproduct hook available in the react autonomy package version >= 2 8 1 useproduct the getprice function returns the price (including discount if applicable) for a product's variant by providing a sku the above use variant price hook could be implemented like this import useswr from 'swr' import { useproduct, variantpriceinput, } from '@chordcommerce/react autonomy' import { tousdcurrency } from ' /utils' export default function usevariantprice( input variantpriceinput, price? number, regularprice? number, ) { const { getprice } = useproduct() const { data, error } = useswr( \[input, 'get price'], (input) => getprice(input), 	 { 	 fallbackdata { 	 variantprice price, regularvariantprice regularprice, 	 } 	 } ) return { variantprice, regularvariantprice, formattedvariantprice tousdcurrency(variantprice), formattedregularvariantprice tousdcurrency(regularvariantprice), isfetchingprice !error && !data, } }