DOCSEARCHbyAlgolia
Submit Docs

Instant Commerce Documentation

website·Indexed 33 days ago

https://docs.instantcommerce.io/

Developer and product guides for Instant Commerce, featuring an SDK for building custom blocks, a JavaScript API, and hooks like useCart, useCustomer, and useShopifyClient. Includes instructions for Shopify integration, managing storefront sections, and configuring shipping zones and product options.

Tokens
21.8K
Snippets
73
Records
191
Agent score
49%

What's inside Instant Commerce

  1. Intercept or cancel the Checkout redirect

    The instantCheckout event is dispatched when the storefront is about to redirect the user to the checkout page. It is cancelable, allowing developers to implement custom logic before manually triggering the redirect using the checkoutUrl provided in the event detail.
    document.addEventListener('instantCheckout', (e) => {
  // Cancel the default redirect
  e.preventDefault();

  // Insert custom logic here

  // Manually redirect to the checkout URL
  window.location.href = e.detail.checkoutUrl;
});

  2. Use the Instant CLI sandbox for block development

    The Instant CLI includes a built-in sandbox enabled by default during project initialization. The sandbox isolates blocks, allowing developers to build and preview them within a simulated Instant Commerce admin environment locally without needing to leave their development environment.

  3. Understand Dynamic Variants constraints and behavior

    Dynamic variants allow you to link multiple separate Shopify products and present them as variants of the same product in an Instant Commerce storefront. This is used when different variants need to display different information (e.g., different images or descriptions), which is not possible with standard Shopify variants.

    Constraints:

    • You can only use dynamic variants for one specific product option type across your entire store (e.g., if you use them for 'Material', you cannot also use them for 'Color' on other products).
    • You can use dynamic variants for different products as long as they share the same option type (e.g., both pants and shirts using 'Material').
    • Each product group must have separate tags to distinguish them.

  4. Understand the difference between Components and Pages in Instant Commerce

    In Instant Commerce, Components and Pages serve different purposes for storefront design:

    • Components: These are blocks designed once and reused across multiple locations in the store. They always display the same content regardless of where they are placed (e.g., a promotional banner or an email pop-up). Note that users cannot create new custom components within the platform.
    • Pages: These act as templates used to display different variations of the same layout. For example, a single 'Product Detail' page template is created, but it dynamically displays different content for every individual product in the store.

  5. Access visitor request data with useRequestData

    Use the useRequestData hook from the @instantcommerce/sdk to retrieve server-side request information about the visitor. It provides two primary properties:

    • country: The country code in ISO 3166-1 Alpha 2 format. Returns "XX" if the country cannot be determined, or "T1" if the visitor is using the TOR network.
    • locale: The Unicode locale identifier for the visitor.
    import { useRequestData } from "@instantcommerce/sdk";

const { country, locale } = useRequestData();

  6. Understand the Instant Commerce headless architecture

    Instant Commerce implements a headless eCommerce architecture by separating the frontend from the backend. In this ecosystem:

    • Frontend: Provided by Instant Commerce.
    • Backend (Product & Order Handling): Provided by Shopify.
    • Content Management (CMS): Provided by Storyblok for managing written and visual content.

  7. Create an 'All products' collection for store overview

    To populate the 'all products' overview, Instant Commerce fetches products from a collection with the handle all. Create an automated collection in Shopify with the condition Price > 0 and ensure Instant Commerce is added to the available sales channels.

  8. Configure the Product Listing Page (PLP) layout

    The Product Listing Page (PLP) serves as a global template for all collection pages across your storefront. To configure the layout and appearance of your PLP, you must add the desired sections to the store in Instant Commerce. This configuration applies universally to all collections.

  9. Access cart data via window.Instant.cart

    The window.Instant.cart object provides access to the current storefront cart state, including the Shopify cart external ID and a list of cart lines. Each line contains details about the product, variant, quantity, and custom attributes.
    window.Instant.cart = {
    "externalId": "gid://shopify/Cart/e29bf31b9c8f37075c1b60fd7cc4941f",
    "lines": [
        {
            "id": "gid://shopify/CartLine/...",
            "product": { "id": "...", "handle": "...", "title": "..." },
            "variant": { "id": "...", "title": "..." },
            "quantity": 5,
            "attributes": [{ "key": "Initials", "value": "BJ" }]
        }
    ]
}

  10. Intercept add-to-cart actions with the instantAddToCart event

    The storefront dispatches the instantAddToCart event whenever a product is about to be added to the cart. This event is cancelable, allowing developers to implement custom validation or logic to prevent the item from being added.

  12. Use Tailwind CSS utility classes in Instant

    Instant supports Tailwind CSS utility classes for every block in a project. This allows developers to apply styles using predefined utility classes (e.g., text-lg for font size) instead of writing custom CSS. The integration also supports the standard Tailwind configuration file, enabling customization of default settings (such as adjusting the lg fontSize) to match specific design requirements.