JavaScript API
Window objects
window.Instant objects provide several blocks with storefront data, such as cart and customer information, as well as some helpful functions, eg. to show toasts.
Cart
In the dropdown you can see the information that is available on the window.Instant.cart object:
window.Instant.cart
window.Instant.cart{
"addLine": Function,
// Contains the Shopify cart ID
"externalId": "gid://shopify/Cart/e29bf31b9c8f37075c1b60fd7cc4941f",
"lines": [
{
"attributes": [{
"key": "Initials",
"value": "BJ"
}],
"id": "gid://shopify/CartLine/5af81736b0b27adf6ce87b2c5e81b3ef?cart=c62a95368e445cfbafdb756c50300387",
"product": {
"id": "gid://shopify/Product/7357686874282",
"handle": "adapt-fleck-seamless-long-sleeve-crop-top",
"title": "ADAPT FLECK SEAMLESS LONG SLEEVE CROP TOP",
},
"variant": {
"id": "gid://shopify/ProductVariant/42907954839722",
"title": "XS / Black"
},
"quantity": 5
},
...
],
"updateLines": Function
}
Add products to cart
You can use the window.Instant.cart object to add products to the cart with the addLine function.
addLine functionwindow.Instant.cart.addLine = (params: {
// Add attributes to the cart line
attributes?: Array<{ key: string; value: string; }>
// Error callback
onError?(e: unknown): void;
// Success callback, includes the cart object
onSuccess?(cart: CartShopify): void;
// The Shopify product ID to add
productId: string;
// @default 1
quantity?: number;
// Show cart modal on success
showModalOnSuccess?: boolean;
// The Shopify product variant ID to add
variantId: string;
}) => Promise<CartShopify>
addLine examplewindow.Instant.cart.addLine({
attributes: [{
key: "Initials",
value: "BJ"
}],
productId: "gid://shopify/Product/7357686874282",
quantity: 2,
showModalOnSuccess: true,
variantId: "gid://shopify/ProductVariant/42907954839722"
});
Update cart lines
You can use the window.Instant.cart object to update cart lines with the updateLines function.
updateLines functionwindow.Instant.cart.updateLines = (params: {
lines: Array<{
// Update cart line attributes, pass empty array to clear
attributes?: Array<{ key: string; value: string; }>
// Line ID of line to update
id: string;
// Update quantity
quantity?: number;
}>;
// Error callback
onError?(e: unknown): void;
// Success callback, includes the cart object
onSuccess?(cart: CartShopify): void;
}) => Promise<CartShopify>
updateLines Examplewindow.Instant.cart.updateLines({
lines: [{
attributes: [{
key: "Initials",
value: "BJ"
}],
id: "gid://shopify/CartLine/fe3b13a2-0888-4091-a1e3-594c5a0f84db?cart=c7d084d11c58b1d99703aa94e04f07f2",
quantity: 2
}]
});
Requests
The window.Instant.request object contains information about the visitor’s requests to the server, which can be used to add personalizations based on specific parameters, such as visitor’s country.
window.Instant.request
window.Instant.request {
// Country code in the ISO 3166-1 Alpha 2 format.
// In case the country could not be determined, the value will be "XX".
// In case the visitor is on the TOR network, the value will be "T1".
country: "NL",
// Unicode locale identifier
locale: "nl"
}
Toast
The window.Instant.Toast object is a Toast; a non-disruptive message that appears on top of the interface to provide quick and short feedback on the outcome of an action. It is used to convey general confirmation for actions that aren’t critical.
window.Instant.Toast
window.Instant.Toast{
create: (
options: {
message: string;
type?: "info" | "success" | "warning" | "error";
position?: "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"
// Duration to show toast for in ms
// @default 8000
duration?: number;
className?: string;
id?: string;
style?: React.CSSProperties;
}
) => {
id: String;
// Dismiss the toast (plays exit animation)
dismiss: () => void;
// Remove the toast (immediate without animation)
remove: () => void;
},
// Dismiss all toasts (plays exit animation)
dismissAll: () => void;
// Remove all toasts (immediate without animation)
removeAll: () => void;
}
window.Instant.Toast Exampleconst toast = window.Instant.Toast.create({
message: "Test",
position: "top-left",
duration: Infinity
});
toast.dismiss();
Events
Add to cart
When a product is going to be added to the cart, the storefront will dispatch the instantAddToCart event. This event is cancelable, so an event listener can be implemented to prevent it from taking place. You can implement your own logic to do this.
instantAddToCart event
instantAddToCart event/** @event instantAddToCart */
CustomEvent {
cancelable: true,
detail: {
product: {
"id":"gid://shopify/Product/6611558793316",
"title":"Otti Combat Boot",
"description":"Bokma Bourbon Cask 5Y is a true competitor of a classic bourbon. Aged for 5-years in American oak, but still a real Dutch genever. Perfect for the bourbon lover who likes to try something new or to give our latest generation a chance to meet this genuinely unique but traditional Dutch drink. A refined recipe, but now brand new. 0.7L - 38% Vol.",
"descriptionHtml":"<meta charset=\"utf-8\"><meta charset=\"UTF-8\">\n<p data-mce-fragment=\"1\">Bokma Bourbon Cask 5Y is a true competitor of a classic bourbon. Aged for 5-years in American oak, but still a real Dutch genever. <br data-mce-fragment=\"1\">Perfect for the bourbon lover who likes to try something new or to give our latest generation a chance to meet this genuinely unique but traditional Dutch drink. <br data-mce-fragment=\"1\">A refined recipe, but now brand new.<br data-mce-fragment=\"1\"></p>\n<p data-mce-fragment=\"1\"><em data-mce-fragment=\"1\">0.7L - 38% Vol.</em></p>\n<br>",
"handle":"otti-combat-boot",
"vendor":"Sunny Shoes",
"productType":"",
"tags":[
...
],
"seo":{
"title":null,
"description":null
},
"images":[
{
"__typename":"Image",
"id":"gid://shopify/ProductImage/28455055229028",
"url":"https://cdn.shopify.com/s/files/1/0549/8345/8916/products/mlouye-combat-boots-milky-1_1100x_ab111ac6-ff11-48fb-a33a-89f2666031f8.jpg?v=1635280951",
"altText":null,
"width":1100,
"height":1100
},
...
],
"compareAtPriceRange":{
"maxVariantPrice":{
"currencyCode":"EUR",
"amount":"0.0"
},
"minVariantPrice":{
"currencyCode":"EUR",
"amount":"0.0"
}
},
"priceRange":{
"maxVariantPrice":{
"currencyCode":"EUR",
"amount":"595.0"
},
"minVariantPrice":{
"currencyCode":"EUR",
"amount":"595.0"
}
},
"variants":[
{
"id":"gid://shopify/ProductVariant/39464808546404",
"title":"Black / 38",
"availableForSale":true,
"sku":"",
"image":{
"__typename":"Image",
"id":"gid://shopify/ProductImage/28455055229028",
"url":"https://cdn.shopify.com/s/files/1/0549/8345/8916/products/mlouye-combat-boots-milky-1_1100x_ab111ac6-ff11-48fb-a33a-89f2666031f8.jpg?v=1635280951",
"altText":null,
"width":1100,
"height":1100
},
"priceV2":{
"currencyCode":"EUR",
"amount":"595.0"
},
"compareAtPriceV2":null,
"selectedOptions":[
{
"name":"Color",
"value":"Black"
},
{
"name":"Size",
"value":"38"
}
]
},
...
],
"selectedVariant":{
"id":"gid://shopify/ProductVariant/39464808546404",
"title":"Black / 38",
"availableForSale":true,
"sku":"",
"image":{
"__typename":"Image",
"id":"gid://shopify/ProductImage/28455055229028",
"url":"https://cdn.shopify.com/s/files/1/0549/8345/8916/products/mlouye-combat-boots-milky-1_1100x_ab111ac6-ff11-48fb-a33a-89f2666031f8.jpg?v=1635280951",
"altText":null,
"width":1100,
"height":1100
},
"priceV2":{
"currencyCode":"EUR",
"amount":"595.0"
},
"compareAtPriceV2":null,
"selectedOptions":[
{
"name":"Color",
"value":"Black"
},
{
"name":"Size",
"value":"38"
}
]
},
"sellingPlanGroups":[
...
]
},
// Call this to still add to cart after defaultPrevented
resume: async () => void
}
}
AddToCart cancelation exampledocument.addEventListener('instantAddToCart', (e) => {
// Cancel the event
e.preventDefault();
// Insert some custom logic here
// Continue adding to cart
e.detail.resume();
});
Checkout
When the storefront is going to redirect to the checkout, it will dispatch the instantCheckout event. This event is cancelable, so an event listener can be implemented to prevent the redirect from taking place, allowing you to implement your own logic to do this.
checkout event
checkout event/** @event instantCheckout */
CustomEvent {
cancelable: true,
detail: {
checkoutUrl: "https://sunny-shoe.myshopify.com/cart/c/e29bf31b9c8f37075c1b60fd7cc4941f?locale=en"
}
}
Checkout cancelation exampledocument.addEventListener('instantCheckout', (e) => {
// Cancel the event
e.preventDefault();
// Insert some custom logic here
window.location.href = e.detail.checkoutUrl;
});
Page load
When a page is loaded in the storefront, after navigating, the storefront dispatches the event instantLoadPage. The type of the page is passed to the event details. You can use this to execute specific logic on the cart page.
`LoadPage` event
/** @event instantLoadPage */
CustomEvent {
cancelable: false,
detail: {
// Page type, can be: 'account', 'activate-account', 'blog-post', 'blog',
// 'cart', 'forgot-password', 'home', 'login', 'product-listing',
// 'product-detail', 'register', 'search', 'wishlist', 'dynamic'
"page": "cart"
}
}
Update cart line
When someone changes quantity on a line of the cart, the storefront will dispatch the instantUpdateCartLine event. This event is cancelable, so an event listener can be implemented to prevent the quantity change from taking place.
UpdateCartLine event example/** @event instantUpdateCartLine */
CustomEvent {
cancelable: true,
detail: {
"lineId": "gid://shopify/CartLine/5af81736b0b27adf6ce87b2c5e81b3ef?cart=c62a95368e445cfbafdb756c50300387",
"quantity": 3
}
}
UpdateCartLine cancelation exampledocument.addEventListener('instantUpdateCartLine', (e) => {
// Cancel the event
e.preventDefault();
// Insert some custom logic here
});
Subscribe to newsletter
When someone enters their email and clicks subscribe to newsletter, the storefront will dispatch the instantSubscribeToNewsletter event. This event is cancelable, so an event listener can be implemented to prevent the default API call from taking place, allowing you to implement your own API.
When canceling, make sure that eventually you call onError or onSuccess, so the storefront knows when the newsletter form is no longer in a loading state.
SubscribeToNewsletter event example /** @event instantSubscribeToNewsletter */
CustomEvent {
cancelable: true;
detail: {
input: {
email: string;
type: "SHOPIFY" | "KLAVIYO" | "MAILCHIMP";
};
onSuccess(showToast?: boolean): void;
onError(message: string): void;
}
}
SubscribeToNewsletter cancelation exampledocument.addEventListener('instantSubscribeToNewsletter', (e) => {
// Cancel the event
e.preventDefault();
// Insert some custom logic here
e.detail.onSuccess(true);
});