Maestra's Shopify Native Integration

Integration is managed by your Maestra Forward Deployed Marketer.

To get started, share your store’s collaborator code with your Maestra marketer. They will send a collaborator request from Maestra’s Shopify account, which has to be accepted. After you grant the necessary permissions (e.g., “Manage and add custom pixels”), the rest of the integration will be handled by them.

✅ To-do

Share your store’s collaborator invitation code with your Maestra marketer
Grant the necessary permissions so Maestra can exchange data with your store

🔧 What Your Maestra Marketer Will Do

Install the Custom App
Embed the JavaScript Tracker into the theme

This tracker captures site events such as product browsing, category browsing, cart interactions, and more.

<script>
    maestra = window.maestra || function() { maestra.queue.push(arguments); };
    maestra.queue = maestra.queue || [];
    maestra('create', {
        endpointId: '<Endpoint ID>'
    });
</script>
<script src="https://api.maestra.io/scripts/v1/tracker.js" async></script>

maestra = window.maestra || function() { maestra.queue.push(arguments); };
maestra.queue = maestra.queue || [];
maestra('create', {
  endpointId: '<Endpoint ID>'
});

var script = document.createElement("script");
script.src = "https://api.maestra.io/scripts/v1/tracker.js";
document.getElementsByTagName('head')[0].appendChild(script);

Add the Maestra Pixel
Activate the pixel under Shopify → Customer Events to complete the connection.

window.maestra = window.maestra || function() { maestra.queue.push(arguments); };
window.maestra.queue = window.maestra.queue || [];

const script = document.createElement('script');
script.setAttribute('src', 'https://api.maestra.io/scripts/v1/tracker.js');
script.setAttribute('async', '');
document.head.appendChild(script);
window.maestra('create', {
  endpointId: 'ENDPOINTID'
});


analytics.subscribe("product_added_to_cart", (event) => {
  if (!event.data?.cartLine?.merchandise?.id) return;

  window.maestra("async", {
    operation: "addtoCart",
    data: {
    addProductToList: {
      pricePerItem: event.data?.cartLine?.merchandise?.price?.amount,
      product: {
        ids: {
          shopifyId: event.data?.cartLine?.merchandise?.id
        }
      }
    }
  },
    onSuccess: function() { },
    onError: function(error) { }
  });
});

// Cart manipulation events subscription

analytics.subscribe("product_removed_from_cart", (event) => {
  if (!event.data?.cartLine?.merchandise?.id) return;

  window.maestra("async", {
    operation: "removefromCart",
    data: {
    removeProductFromList: {
      pricePerItem: event.data?.cartLine?.merchandise?.price?.amount,
      product: {
        ids: {
          shopifyId: event.data?.cartLine?.merchandise?.id
        }
      }
    }
  },
    onSuccess: function() { },
    onError: function(error) { }
  });
});

// Checkout completed event subscription

analytics.subscribe("checkout_completed", (event) => {
  maestra("async", {
	  operation: "CheckoutCompleted",
	  data: {
	    customer: {
	      ids: {
	        shopifyCustomerId: event.data.checkout.order?.customer?.id
	      }
	    }
	  }
	});
});

// Part to track events during cart views & checkout

analytics.subscribe("checkout_started", (event) => {
  const data = {
    productList: event.data.checkout.lineItems.map(function(item) {
      return {
        count: item.quantity,
        pricePerItem: item.variant.price.amount,
        product: {
          ids: {
            shopifyId: item.variant.id
          }
        }
      }
    })
  };
  if (event.data.checkout.email) {
    data.customer = data.customer || { customFields: {} };
    data.customer.email = event.data.checkout.email;
    if (event.data.checkout.buyerAcceptsEmailMarketing) {
      data.customer.customFields.subscriptionShopifyEmail = event.data.checkout.buyerAcceptsEmailMarketing;
    }
  }
  if (event.data.checkout.smsMarketingPhone) {
    data.customer = data.customer || { customFields: {} };
    data.customer.phone = event.data.checkout.smsMarketingPhone;
    if (event.data.checkout.buyerAcceptsSmsMarketing) {
      data.customer.customFields.subscriptionShopifySms = event.data.checkout.buyerAcceptsSmsMarketing;
    }
  }
  if (event.data.checkout?.shippingAddress?.country === 'US' && event.data.checkout?.shippingAddress?.zip) {
    data.customer = data.customer || { customFields: {} };
    data.customer.area = { ids: { externalId: event.data.checkout.shippingAddress.zip } };
  }
  if (event.data.checkout.billingAddress?.countryCode) {
    data.customer = data.customer || { customFields: {} };
    data.customer.customFields.countryCode = event.data.checkout.billingAddress?.countryCode;
  }
  if (event.data.checkout?.shippingAddress?.country) {
    data.customer = data.customer || { customFields: {} };
    data.customer.customFields.country = event.data.checkout.shippingAddress.country;
  }

  const operationName = (data.customer && (data.customer.email || data.customer.phone)) ? 'CheckoutStarted' : 'CheckoutStartedNoCustomerInfo';
  try {
    if (operationName === 'CheckoutStarted') {
      data.customer.timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
    }
  } catch (e) {}
  
  maestra("async", {
    operation: operationName,
    data: data,
  });
});

analytics.subscribe("checkout_shipping_info_submitted", (event) => {
  const data = {
    productList: event.data.checkout.lineItems.map(function(item) {
      return {
        count: item.quantity,
        pricePerItem: item.variant.price.amount,
        product: {
          ids: {
            shopifyId: item.variant.id
          }
        }
      }
    })
  };
  if (event.data.checkout.email) {
    data.customer = data.customer || { customFields: {} };
    data.customer.email = event.data.checkout.email;
    if (event.data.checkout.buyerAcceptsEmailMarketing) {
      data.customer.customFields.subscriptionShopifyEmail = event.data.checkout.buyerAcceptsEmailMarketing;
    }
  }
  if (event.data.checkout.smsMarketingPhone) {
    data.customer = data.customer || { customFields: {} };
    data.customer.phone = event.data.checkout.smsMarketingPhone;
    if (event.data.checkout.buyerAcceptsSmsMarketing) {
      data.customer.customFields.subscriptionShopifySms = event.data.checkout.buyerAcceptsSmsMarketing;
    }
  }
  if (event.data.checkout?.shippingAddress?.country) {
    data.customer = data.customer || { customFields: {} };
    data.customer.customFields.country = event.data.checkout.shippingAddress.country;
  }
  if (event.data.checkout?.shippingAddress?.country === 'US' && event.data.checkout?.shippingAddress?.zip) {
    data.customer = data.customer || { customFields: {} };
    data.customer.area = { ids: { externalId: event.data.checkout.shippingAddress.zip } };
  }
  // code to transfer country to country customField
  if (event.data.checkout.shippingAddress?.country) {
    data.customer = data.customer || { customFields: {} };
    data.customer.customFields.country = event.data.checkout.shippingAddress?.country;
  }


  const operationName = (data.customer && (data.customer.email || data.customer.phone)) ? 'CheckoutStarted' : 'CheckoutStartedNoCustomerInfo';
  try {
    if (operationName === 'CheckoutStarted') {
      data.customer.timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
    }
  } catch (e) {}
  
  maestra("async", {
    operation: operationName,
    data: data,
  });
});

analytics.subscribe("checkout_contact_info_submitted", (event) => {
  const data = {};
  if (event.data.checkout.email) {
    data.customer = data.customer || { customFields: {} };
    data.customer.email = event.data.checkout.email;
    if (event.data.checkout.buyerAcceptsEmailMarketing) {
      data.customer.customFields.subscriptionShopifyEmail = event.data.checkout.buyerAcceptsEmailMarketing;
    }
  }
  if (event.data.checkout.smsMarketingPhone) {
    data.customer = data.customer || { customFields: {} };
    data.customer.phone = event.data.checkout.smsMarketingPhone;
    if (event.data.checkout.buyerAcceptsSmsMarketing) {
      data.customer.customFields.subscriptionShopifySms = event.data.checkout.buyerAcceptsSmsMarketing;
    }
  }
  
  maestra("async", {
    operation: "CheckoutContactInfoSubmitted",
    data: data,
  });
});

analytics.subscribe("cart_viewed", (event) => {
  if (!event.data.cart || !event.data.cart.lines.length) return;
  
  const data = {
    productList: event.data.cart?.lines.map(function(item) {
      return {
        count: item.quantity,
        pricePerItem: item.merchandise.price.amount,
        product: {
          ids: {
            shopifyId: item.merchandise.id
          }
        }
      }
    })
  };
  maestra("async", {
    operation: "SetCart",
    data: data,
  });
});

Once these three steps are complete, your Shopify store will be fully connected to the Maestra CDP.

👤⚙️Self-Setup Option

If you’d prefer to handle the setup yourself, your Maestra marketer will be happy to guide you through the process.