Storefront SDK
The Downpay storefront integration exposes certain settings and JavaScript hooks which you can use to create custom solutions. This can be used for, amongs other things, creating integrations with other apps. For example, product options or calendar booking apps that wish to support deposits and partial payments.
Downpay integrates deeply with Shopify by taking advantage of Shopify's Selling Plans APIs. To add a product to the cart with a partial payment option, a selling plan ID must be passed to the Shopify Cart API when adding a line item to the cart. You can find the selling plan ID inside the Downpay app, at the top of the purchase option customization form. This ID must be included on the line item when the item is added to the cart. This can be done in two ways:
By default, the Downpay product block will add a hidden <input> element to the product form. This input will contain a selling plan id. When the customer clicks the Add to Cart button and the form is submitted, the storefront theme will serialize this input and pass it along in the call to the Cart API. This <input> elements looks like this:
The value attribute of the input is the selling plan ID.
The other way to add a selling plan to the line item that is getting added to the cart is to include the ID of the selling plan into the AJAX call to the cart. More information can be found in the official Shopify documentation here.
For many use cases, you can hardcode the selling plan id you wish to use with the line items you add to the cart.
At other times, especially on product pages where the customer may interact with the Downpay product block, the customer may select a variant or another option which changes the selected selling plan id.
If you would like to create any sort of custom integration with Downpay's product page extension, you will first need to access the selling plan id associated with the current customer selection. This can be done in two ways:
Downpay exposes a global object in the browser that exposes the currently selected selling plan ID, which can be accessed in JavaScript by calling window.downpay.selected_selling_plan_id. You can call this at any time to get the current selling plan selection. If the customer has not selected any options with a selling plan, this value will be null
Whenever a selling plan selection changes, Downpay will emit an event with the name downpay:selling-plan:change. You can listen to this event to be informed of this change, like so:
You may find yourself needing to know when the Downpay product block has finished initializing. You can do this by listening to the downpay:product:loaded event. For example:
A note on Selling Plans
Downpay integrates deeply with Shopify by taking advantage of Shopify's Selling Plans APIs. To add a product to the cart with a partial payment option, a selling plan ID must be passed to the Shopify Cart API when adding a line item to the cart. You can find the selling plan ID inside the Downpay app, at the top of the purchase option customization form. This ID must be included on the line item when the item is added to the cart. This can be done in two ways:
Form serialization
By default, the Downpay product block will add a hidden <input> element to the product form. This input will contain a selling plan id. When the customer clicks the Add to Cart button and the form is submitted, the storefront theme will serialize this input and pass it along in the call to the Cart API. This <input> elements looks like this:
<input id="selected-purchase-option" type="hidden" name="selling_plan" value="8157430046">The value attribute of the input is the selling plan ID.
JavaScript
The other way to add a selling plan to the line item that is getting added to the cart is to include the ID of the selling plan into the AJAX call to the cart. More information can be found in the official Shopify documentation here.
Fetching the currently selected selling plan id
For many use cases, you can hardcode the selling plan id you wish to use with the line items you add to the cart.
At other times, especially on product pages where the customer may interact with the Downpay product block, the customer may select a variant or another option which changes the selected selling plan id.
If you would like to create any sort of custom integration with Downpay's product page extension, you will first need to access the selling plan id associated with the current customer selection. This can be done in two ways:
The global settings object
Downpay exposes a global object in the browser that exposes the currently selected selling plan ID, which can be accessed in JavaScript by calling window.downpay.selected_selling_plan_id. You can call this at any time to get the current selling plan selection. If the customer has not selected any options with a selling plan, this value will be null
Listen to an event
Whenever a selling plan selection changes, Downpay will emit an event with the name downpay:selling-plan:change. You can listen to this event to be informed of this change, like so:
window.addEventListener("downpay:selling-plan:change", function(e) {
const sellingPlanId = e.detail.sellingPlanId;
console.log(sellingPlanId);
});Listening to Downpay product block initialization
You may find yourself needing to know when the Downpay product block has finished initializing. You can do this by listening to the downpay:product:loaded event. For example:
window.addEventListener("downpay:product:loaded", function(e) {
console.log("Downpay has finished loading");
});Updated on: 24/05/2025
Thank you!