# Functions {% hint style="info" %} The documentation below describes the API as of version 9.x of the script. Public properties or functions that are not in the `discountNinja.api` namespace should be considered obsolete and will be removed in the next major version release. Using undocumented functions or objects will result in issues as custom code that relies on those functions or objects may break in the future when Discount Ninja's script is automatically updated. {% endhint %} ## Cache ### Clear


Async	Yes
Function	`await discountNinja.api.cache.clear()`
	Clears all session and local storage data used by the script. Also clears the content of the indexedDb used by the script.
Type	Public
	This function is intended for use in troubleshooting sessions.

#### Syntax ```javascript //Clear cache if (discountNinja) await discountNinja.api.cache.clear(); ``` ## Cart ### Add


Async	Yes
Function	`await discountNinja.api.cart.add(variant: number, quantity: number, properties?: Record<string, string>, sellingPlanId?: number)`
	Adds a variant to the cart. Note: this is an asynchronous function; the result must be awaited.
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	`variant (number)`: the variant id
	`quantity (number)`: the number of items to add
	`properties? (Record<string, string>)`: an optional object with key/value pairs of line item properties
	`sellingPlanId? (number)`: an optional selling plan (to allow for recurring purchases based on a subscription)

#### Syntax ```javascript async function addVariantToCart() { if (!discountNinja) return; const variant = 123456; //Ensure the variant id exists on the shop const quantity = 1; const properties = { "my_property": "my value", "my_property_2": "another value" }; const sellingPlanId = 123456; //Ensure this is a valid selling plan for the variant //Add the variant await discountNinja.api.cart.add(variant, quantity); //Add the variant with a line item property await discountNinja.api.cart.add(variant, quantity, properties); //Add the variant with a selling plan await discountNinja.api.cart.add(variant, quantity, undefined, sellingPlanId); } //Run the above test await addVariantToCart(); ``` ### Content


Async	No
Property	`discountNinja.api.cart.content`
	Can be used to get access to an object that represents the content of the cart, including any discounts applied by Shopify's backend.
Type	Public
	This function is intended for use in integration code by third parties.
Return value	`object \| null` Returns the Shopify cart object. Returns null if no cart is available.

#### Syntax ```javascript function logShopifyCart() { const cart = discountNinja discountNinja.api.cart.content ? null; const itemCount = cart ? cart.item_count : 0; console.log(`There are currently ${itemCount} items in the cart`, cart); } logShopifyCart() ``` ### Prefill


Async	Yes
Property	`await discountNinja.api.cart.prefill(variants?: string[], redirectUrl?: string)`
	Can be used to prefill a cart with specific variants. Typically used to create a link to a prefilled, discounted cart. Cf. https://support.discountninja.io/en/articles/5194395-how-to-build-a-prefilled-discounted-cart
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	`variants?: string[]`: a comma-separated list of the variant id of the product variants you want to add to the cart; for each variant you'll need to specify the quantity.
	This parameter is optional. If it is omitted, the app will look for a query parameter named `variants` instead. If neither is available the prefill method will not execute.
	`redirectUrl?: string`: define which page should be loaded once the cart is prefilled
	This parameter is optional. If it is omitted, the app will look for a query paramer named `redirectUrl` instead. If neither is available the default value is "`/cart`".

#### Syntax: example 1 This script can be used on a cart template to automatically prefill the cart based on the query parameters as explained here: [ttps://support.discountninja.io/en/articles/5194395-how-to-build-a-prefilled-discounted-cart](https://support.discountninja.io/en/articles/5194395-how-to-build-a-prefilled-discounted-cart) ```javascript ``` #### Syntax: example 2 Alternatively, create a variants array manually and then ```javascript async function prefillCartWithSpecificVariants() { // Replace 123456 and 2345678 with valid variant ids // Add a quantity of 1 of the variant with id 1234567x1 // and a quantity of 2 of the variant with id 2345678x2 // then, redirect to the home page const variants = []; variants.push('1234567x1'); variants.push('2345678x2'); if (discountNinja) await discountNinja.api.cart.prefill(variants, '/'); } await prefillCartWithSpecificVariants(); ``` ## Checkout ### Is discounted


Async	Yes
Function	`await discountNinja.api.checkout.isDiscounted()`
	Can be used to check if any of the promotions apply to the cart and result in a product, order or shipping discount.
Type	Public
	This function is intended for use in integration code by third parties.
Return value	`Promise<boolean>` Returns a promise which resolves to a `boolean`. The return value indicates if the app will instruct Shopify to apply discounts at checkout. Additionally, when this function returns `true`, the script will attempt to take over the checkout process when the cart form is submitted using a checkout button.

#### Syntax ```javascript document.addEventListener("la:dn:cart:updated", async function(event) { const discountedCart = event.detail.data[0]; const isDiscounted = await discountNinja.api.checkout.isDiscounted(); if (isDiscounted) { console.log('The cart is discounted', discountedCart); // Add logic when the cart is discounted by Discount Ninja offers } else { console.log('The cart is not discounted', discountedCart); // Add logic when the cart is not discounted by Discount Ninja offers } }); ``` ### Add pipeline rule


Async	No
Function	`discountNinja.api.checkout.addPipelineRule()`
	Can be used to add custom business logic that is executed when the customer click the checkout button.
	Discount Ninja needs to take over the checkout process when a user clicks the checkout button to ensure the checkout is correctly discounted.
	As a result, the app overrides any logic you may have associated with clicking the checkout button. To execute this logic you can add it to the pipeline of rules that is executed by the app.
	Each pipeline rule is a parameterless function that returns a boolean indicating if execution should continue (`true`) or not (`false`).
Type	Public
	This function is intended for use in integration code by third parties.
Return value	`boolean` The return value indicates if the rule was added properly.

#### Syntax ```javascript function checkoutPipelineRule1() { //Add your logic here //Return true to indicate that the customer can continue to the checkout //Return false to halt the pipeline console.log('Executing checkout pipeline rule 1'); return true; } function checkoutPipelineRule2() { //Add your logic here //Return true to indicate that the customer can continue to the checkout //Return false to halt the pipeline console.log('Executing checkout pipeline rule 2'); return true; } function registerCheckoutPipelineRules() { const successfullyAddedRule1 = discountNinja.api.checkout.addPipelineRule(checkoutPipelineRule1); const successfullyAddedRule2 = discountNinja.api.checkout.addPipelineRule(checkoutPipelineRule2); if (successfullyAddedRule1 && successfullyAddedRule2) { console.log('Pipeline rules successfully registered'); } else { console.error('Pipeline rules could not be registered'); } } //Check if the API is ready if (typeof discountNinja === 'undefined' || typeof discountNinja.api === 'undefined') { //The API is not ready, wait for it document.addEventListener("la:dn:api:ready", function(event) { registerCheckoutPipelineRules(); }); } else { //The API was already available, no need to wait registerCheckoutPipelineRules(); } ``` ### With


Async	Yes
Property	`await discountNinja.api.checkout.with(variants: string[], discountCodes?: string[])`
	Can be used to checkout using specific variants and one or more discount codes.
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	`variants?: string[]`: a comma-separated list of the variant id of the product variants you want to add to the cart; for each variant you'll need to specify the quantity. The variant and the quantity are separated by an x. E.g. 123456x2
	`discountCodes?: string[]`: a list of discount codes to apply to the cart

#### Example This example shows you can use this api method to build a discounted checkout link, that can be used on any page that includes the Discount Ninja App embed. ```javascript Checkout with selected items ``` ## Discount code ### Add


Async	Yes
Function	`await discountNinja.api.discountCode.add(discountCode: string)`
	Adds a discount code or promotion code to the Discount Ninja promotion code field programmatically.
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	`discountCode (string)`: the discount code to add

#### Syntax ```javascript async function addDiscountCode(discountCode) { if (discountNinja) await discountNinja.api.discountCode.add(discountCode); console.log(`Added the promotion with promotion code '${discountCode}' to the cart`); } await addDiscountCode('WELCOME10'); ``` ### Remove


Async	Yes
Function	`await discountNinja.api.discountCode.remove(discountCode: string)`
	Removes a discount code or promotion code from the Discount Ninja promotion code field programmatically.
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	`discountCode (string)`: the discount code to remove

#### Syntax ```javascript async function removeDiscountCode(discountCode ) { if (discountNinja) await discountNinja.api.discountCode.remove(discountCode); console.log(`Removed the promotion with promotion code '${discountCode}' from the cart`); } await removeDiscountCode('WELCOME10'); ``` ## Discounted cart ### Content


Property	`discountNinja.api.discountedCart.content`
	Can be used to get access to an object that represents the content of the cart, including any discounts applied by Shopify's backend.
Type	Internal
	This is an internal function or property. Use it only for debugging purposes. Do not rely on this function or property in your integration code.
Return value	`object \| null` Returns an object representing the current cart, with the applicable Discount Ninja offers applied. Note that amounts returned are in cents, not in dollars.

#### Syntax ```javascript function logDiscountedCart() { const discountedCart = discountNinja ? discountNinja.api.discountedCart.content : null; console.log(`The discounted cart`, discountedCart); } logDiscountedCart() ``` ## Entitlements


Property	`discountNinja.api.entitlements`
	Lists the entitlements that apply based on the available offers. The array contains one item for each available offer. It details the prerequisites that were found in the cart, the discount amount, the target products and the entitled line items that were found in the cart.
Type	Public
	This function is intended for use in integration code by third parties..
Return value	`object[] \| null` Returns an array of Entitement info objects.

#### Syntax ```javascript function logEntitlements() { if (discountNinja) console.log(`Entitlements`, discountNinja.api.entitlements); } logEntitlements() ``` ## Events ### Subscribe {% hint style="warning" %} This function is not used to subscribe to events. Instead it is simply a helper function that prints sample code to the log console to explain how to subscribe to an event. {% endhint %}


Async	No
Function	`discountNinja.api.events.subscribe(eventName: string)`
	Provides instructions on how to subscribe to an event with a given name. Note: this function does not, itself, subscribe to the event.
	See the list of available events.
Type	Public
	This function is intended for use in integration code by third parties.

#### Syntax

function printInstructionsToSubscribeToEvent(event) {
    if (discountNinja) discountNinja.api.events.subscribe(event);
}

printInstructionsToSubscribeToEvent('cart:updated')
// Prints the following message on the console:
// To subscribe to this event use the following code: 
// document.addEventListener("la:dn:cart:updated", function(event) { const eventData = event.detail.data[0]; console.log('Event la:dn:cart:updated was published.', eventData); });

### Publish


Async	No
Function	`discountNinja.api.events.publish(eventName: string)`
	Publishes an event to the PriceRuleEngine.
	See the list of available events.
Type	Public
	This function is intended for use in integration code by third parties.

#### Syntax ```javascript function test() { if (discountNinja) discountNinja.api.events.publish('cart:updated'); } ``` ## Help


Async	No
Function	`discountNinja.api.help()`
	Prints a link to this page on the console.
Type	Public
	This function is intended for use in integration code by third parties.

#### Syntax ```javascript discountNinja.api.help() ``` ## Line item ### Get updated key


Async	No
Function	`discountNinja.api.lineItem.getUpdatedKey(key: string)`
	Returns the updated key associated with a cart line item. A key can be updated by Shopify's back-end when properties are added, a selling plan changes or a discount is added. Cf. https://support.discountninja.io/en/articles/9109023-fix-network-requests-to-cart-js
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	`key (string)`: the original key of the cart line item
Return value	`string` The updated key.

#### Syntax ```javascript function test() { for (let i = 0; i < cart.items.length; i++) { const item = cart.items[i]; let key = item.key; if (discountNinja) { key = discountNinja.api.lineItem.getUpdatedKey(key); } // ... use the updated key, for example, to send requests to cart.js } }); ``` ## Offers ### All


Async	No
Function	`discountNinja.api.offers.all`
	Lists all the active offers loaded by the app.
Type	Internal
	This function returns an internal object. Do not rely on the properties of this object in your integration code as they may be removed or renamed in future versions.
Return value	`object[]` An array of `offer` objects, representing the offers that are applicable in the current context.

#### Syntax ```javascript document.addEventListener("la:dn:promotions:loaded", function(event) { const offers = discountNinja ? discountNinja.api.offers.all : null; console.log('Offers loaded', offers); }); ``` ### Get {% hint style="info" %} This function is used to look up an offer that is available in the browser's cache. To load a promotion that is not available to the browser, use the Promotion [Trigger](#trigger) function or the Discount Code [Add](#add-1) function instead. {% endhint %}


Async	No
Function	`discountNinja.api.offers.get(token: string)`
	Finds a specific offer in the list of all the active offers loaded by the app.
Type	Internal
	This function returns an internal object. Do not rely on the properties of this object in your integration code as they may be removed or renamed in future versions.
Parameters	`token (string)`: the token of the offer to find
Return value	`object \| null` An`offer` object if the offer is found, otherwise `null`.

#### Syntax ```javascript document.addEventListener("la:dn:promotions:loaded", function(event) { const offerToken = 'ABCD'; const bfcmOffer = discountNinja ? discountNinja.api.offers.get(offerToken) : null; if (bfcmOffer === null) { console.log(`Offer with token ${offerToken} not found`); } else { console.log(`Offer with token ${offerToken} found`, bfcmOffer); } }); ``` ## Promotions ### All


Function	`discountNinja.api.promotions.all`
	Lists all the active promotions loaded by the app.
Type	Internal
	This function returns an internal object. Do not rely on the properties of this object in your integration code as they may be removed or renamed in future versions.
Return value	`object[]` An array of `promotion` objects, representing the promotions that are applicable in the current context. The promotion object provides information about the trigger used and the list of offers associated with the promotion.

#### Syntax ```javascript document.addEventListener("la:dn:promotions:loaded", function(event) { const promotions = discountNinja ? discountNinja.api.promotions.all : null; console.log('Offers loaded', promotions); }); ``` ### Get {% hint style="info" %} This function is used to look up a promotion that is available in the browser's cache. To load a promotion that is not available to the browser, use the Promotion [Trigger](#trigger) function or the Discount Code [Add](#add-1) function instead. {% endhint %}


Function	`discountNinja.api.promotions.get(token: string)`
	Finds a specific promotion in the list of all the active promotions loaded by the app.
Type	Internal
	This function returns an internal object. Do not rely on the properties of this object in your integration code as they may be removed or renamed in future versions.
Parameters	`token (string)`: the token of the promotion to find
Return value	`object \| null` A `promotion` object if the promotion is found, otherwise `null`.

#### Syntax ```javascript document.addEventListener("la:dn:promotions:loaded", function(event) { const promotionToken = 'ABCD'; const bfcmPromotion = discountNinja ? discountNinja.api.promotions.get(promotionToken) : null; if (bfcmPromotion === null) { console.log(`Promotion with token ${promotionToken} not found`); } else { console.log(`Promotion with token ${promotionToken} found`, bfcmPromotion); } }); ``` ### Trigger


Async	No
Function	`discountNinja.api.promotions.trigger(tokens: string)`
	Triggers a private promotion programmatically.
	Use this as a programmatic alternative to using a discount link. To trigger a promotion based on a promotion code, use the Discount Code Add function instead.
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	`tokens (string \| string[])`: the token(s) of the promotion(s) to trigger

#### Syntax ```javascript function triggerCustomPromotion() { const bcfmPromotionToken = 'ABCD'; if (discountNinja) discountNinja.api.promotions.trigger(bcfmPromotionToken); } ``` ```html Unlock the BFCM promo! ``` ## Strikethrough Pricing ### Apply


Async	Yes
Function	`await discountNinja.api.strikethroughPricing.apply()`
	Triggers a refresh of all strikethrough pricing programmatically. This is typically not required since the app automatically detects situations where the strikethrough pricing must be updated.
	For an event based approach, use this event instead.
Type	Public
	This function is intended for use in integration code by third parties.

#### Syntax ```javascript async function myPriceUpdateLogic() { //Trigger Discount Ninja's strikethrough pricing rendering if (discountNinja) await discountNinja.api.strikethroughPricing.apply(); }; ``` ### Before render


Async	No
Function	`discountNinja.api.strikethroughPricing.setBeforeRender(async (input: Object) => string)`
	Discount Ninja ships with its own internal rendering function wired up as the “before render” callback. This function allows the user to override this callback with a custom callback.
Parameters	`async (input: Object) => string)` A function that receives an input object and returns a string. `priceData: Object` An input object that can be used to decide if the rendered text should be updated. `string` The HTML that should be rendered. To render the HTML proposed by the internal rendering function, simply return input.defaultHtml This is the shape of the `input`object: `{ offerToken: string; defaultHtml: string; // This is the default HTML, computed by the script productInfo: { productHandle: string; variantId: number; sellingPlanId: number \| null; available: boolean; price: { original: number; compareAt: number; discounted: number; }; }; };`
Return value
Type	Public
	This function is intended for use in integration code by third parties.

#### Syntax ```javascript function registerBeforeRenderLogic() { async function beforeRenderLogic(input) { ... custom logic ... return input.defaultHtml; } discountNinja.api.strikethroughPricing.setBeforeRender(beforeRenderLogic); } //Check if the API is ready if (typeof discountNinja === 'undefined' || typeof discountNinja.api === 'undefined') { //The API is not ready, wait for it document.addEventListener("la:dn:api:ready", function(event) { registerBeforeRenderLogic(); }); } else { //The API was already available, no need to wait registerBeforeRenderLogic(); } ``` ## Widgets ### Render


Async	Yes
Function	`await discountNinja.api.widgets.render()`
	Triggers a refresh of all widgets (including strikethrough pricing) programmatically. This is typically not required since the app automatically detects situations where the widgets must be updated.
Type	Public
	This function is intended for use in integration code by third parties.

#### Syntax ```javascript async function myWidgetUpdateLogic() { //Trigger Discount Ninja's widget rendering update if (discountNinja) await discountNinja.api.widgets.render(); }; ``` ## Widgets > Promotion Code Field ### Toggle


Async	Yes
Function	`await discountNinja.api.widgets.promotionCodeField.toggle()`
	Expands or collapses the promotion code field widget.
Type	Public
	This function is intended for use in integration code by third parties.

#### Syntax ```javascript async function myFunction() { if (discountNinja) discountNinja.api.widgets.promotionCodeField.toggle(); }; ``` ### Footer Instructions


Async	No
Function	`discountNinja.api.widgets.promotionCodeField.showFooterInstructions()` `discountNinja.api.widgets.promotionCodeField.hideFooterInstructions()` `discountNinja.api.widgets.promotionCodeField.toggleFooterInstructions()`
	Expands or collapses the instructions section in the footer of the promotion code field.
Type	Public
	This function is intended for use in integration code by third parties.

#### Syntax ```javascript async function myFunction() { if (discountNinja) discountNinja.api.widgets.promotionCodeField.toggleFooterInstructions(); }; ```