Integrate Magento v1

  • Updated

This article covers Magento v1. For Magento v2, click here.

Magento is a very flexible platform that lets you make modifications to the core capabilities for better marketing. The Optimizely Data Platform (ODP) connector integrates with Magento using best practices. If you have concerns with how your Magento store is set up, please reach out to before integrating.

What data is integrated?

  Historical On-Going Type

Customer Data

Yes Yes



Order Data Yes Yes




Product Data Yes Yes



Web Site Data No Yes


product page views

add to cart

remove from cart

newsletter subscribe 

Configure Magento 1.X connector

  1. Download the latest connector package: Zaius_Engage-0.14.2.tgz (Change Log)
  2. Log in to your Magento admin console.
  3. Go to System > Magneto Connect > Magento Connect Manager.


  4. After you log in to the Magento Connect Manager, click Choose File... and select the connector file you downloaded in step one.
  5. Click Upload. You will see a log at the bottom of the page detailing the installation process.
  6. In your Magento admin console, go to System > Configuration.
  7. Under Sales, select Zaius Engage.
    If you get a 404 or permission error when clicking on Zaius Engage, you must log out of your admin session and log back in.
  8. Paste your Tracker ID into the specified text box and click Save.
  9. If the Track Product Listing Views option displays, click Yes.

Congratulations! Your new events will now be sent to ODP.

Magento 1.X permissions setup

To use Magento with ODP, create a user with SOAP API permissions.

  1. Go to System > Web Services > SOAP/XML-RPC - Users. If a user does not already exist, create a new one.


    • You must provide the username and API key that is specified to ODP to enable the integration.
    • This user must have permission to use the ODP Engage API to retrieve data from Magento.

To ensure the user has appropriate permissions:

  1. Go to System > Web Services > SOAP/XML-RPC - Roles to assign appropriate permissions to the user. ODP Engage provides a custom API that is used during the initial import of customers, products, and orders.
  2. Associate the user with the new role.
  3. Go to Integrations > Magento API and enter the Username, API Key, and the API URL for your server. The API URL often looks like this: http://your-magento-server/api/v2_soap?wsdl=1

Configure ODP Engage

ODP Engage provides a set of configuration options for the plugin.

  • Tracking identifier – The ODP Tracker Id.
  • Cart Abandonment Secret Key – A secret value used to encode link information for cart abandonment campaigns. Do not change this once set. This is a random string that you enter not provided by ODP.
  • ODP Schema Update & ODP Batch Updates – Optional but recommended tweaks.

Don't change the other settings unless your customer success manager (CSM) recommends it.

Configure batch updates (0.12.0 and up)

Many Magento sites have a variety of backend processes that run direct SQL inserts and updates, especially ERPs. When a direct SQL modifies the Magento database, Magento's Observers do not inform other technologies (such as ODP) about it, causing those technologies to desynchronize from the Magento dataset.

To account for this, ODP has built a Batch Update module which lives in Magento to find those products, customers, and orders that have been updated since the last scan.

  1. Go to ODP Engage > ODP Schema Update > Run It! so that the batch process knows which entries to sync. This adds two columns to the database tables that ODP syncs: zaius_created_at and zaius_updated_at.
  2. In the ODP Batch Updating panel, change the Crontab line to indicate how frequently you would like the updates to run. More frequent updates mean that each update takes less time to process; however, a small query runs against the database to determine if there is anything ODP needs to sync. ODP recommends either a high-frequency update (such as "*/5 * * * *" meaning every 5 minutes) or a daily batch at a low-traffic time (such as "0 1 * * *" meaning at 1 AM as indicated by your Magento server's clock).
  3. Set the Enable/Disable option to Enable.

Configure localizations (0.13.0 and up)

Many Magento sites support multiple language/currency code combinations and create each one as a separate store_view. 

The ODP Localizations featured in the ODP Engage module adds support for such sites to automatically detects those store_views and send additional, localized versions of products. These products provide all information necessary to generate dynamic product grids in your customers' preferred languages, even for products that have not interacted with.

This feature is  still in a beta phase, meaning that the ODP support team must make certain updates on the ODP platform to fully utilize this feature. Please consult with your CSM to get those changes made prior to initializing this feature.

  1. Go to the ODP Engage configuration page.
  2. Under ODP Localizations, switch Enable/Disable to Enable.

ODP Double Opt-in Beta (0.13.3 and up)

ODP Engage has a new option to support double opt-in workflows. Set the Submit Event For Status Not Active option in the ODP Engage Configuration.

With the Submit Event For Status Not Active option enabled, new users with subscription status 2 ("Not Active") will trigger a "newsletter" event with action "email_submitted."

Users can configure an Event Triggered campaign to allow the user to opt-in and use engagement with that campaign as a filter for their regularly-occurring sends. Your ODP CSM can help set this up.

Magento coupon codes

To add a coupon code in an email in ODP, add the below Liquid to set the rule_id as the ID for the coupon code you want to use.

{% assign coupon_rule = '{"rule_id": 1}' %}
{{ zaius.magento.api_config | magento_v1_coupon_code: coupon_rule }}

You can find this ID in Magento under Promotions > Shopping Cart Price Rules.

Change log

Version Release Log
0.14.2 2019-05-01 * Bugfix. Added fallback timestamp on list events in observer.
0.14.1 2019-01-30 * Bugfix. 'getLangcode' rewritten to 'getLangCode'
0.14.0 2019-01-25 * Removed bulk import legacy subscriber states which had no effect in ODP.
* Added list support to bulk subscriber imports
* Removed unnecessary product listing events which caused significant performance issues.
* Cleaned up localizations for broader compatibility.
* Further updated double opt-in workflows against a stricter audit. Added default to ensure visibility in configuration.
* Added parameter to subscriber API to enable pulling a particular subscriber by email address (for troubleshooting purposes)
0.13.4 2018-11-05 * Updated beta support for double opt-in workflows.
0.13.3 2018-10-22 * Added beta support for double opt-in workflows
* Cleaned up potential undefined case when getting subscriber information (which would have appeared in logs, but didn't interrupt tracking or loading)
0.13.2 2018-09-19 * Hotfixes for a variety of bulk import errors
* Minor tweaks to localizations code for broader compatibility
* Additional logging of errors to ODP-specific logs
* Added product availability field which is populated using the Magento "getIsSalable" function.
0.13.1 2018-07-13 * Hotfixes for tracking live updates to products when using new localizations feature.
0.13.0 2018-07-12 * Localizations Update: Adds support for localized store_views, including inheritance, linking between languages, varied currency reporting, and more. (During the public beta phase, configuration requires support from the ODP team, please contact your Customer Success Manager)
* Improved support for configurable products (more to come)
* Improved and extended APIs to enable the ODP support team to provide more accurate troubleshooting, more quickly.
0.12.2 2018-07-12 * Hotfixes for Coupon Code Support which addresses a case where coupons were not setting the appropriate type, causing the generated codes to be usable multiple times.
0.12.1 2018-06-20 * Hotfixes for Batch Updates which cover more environments and improve consistency of APIs.
0.12.0 2018-06-04 * Further fix for Customer address import issues causing some addresses to be cut off prematurely. If affected, install the update, then ask ODP Support to reimport customers for you.
* Fix for subscriber import and updates ensuring subscribe events are appropriately timestamped - prevents a subscriber synchronization causing all subscribers to appear actively engaged within ODP.
* New Feature: Batch Updates. In certain situations, updates (frequently to products) are not detected by Magento, which meant Magento never updated ODP. This could cause Magento and ODP to get out of sync. We've added an optional component which will configure Magento to send regular updates to ODP. When activated, this feature will add columns to Magento databases (zaius_created_at and zaius_updated_at) so that the batch process can send us updates of only new and updated data points. While we have not previously identified cases beyond the products feed, this feature is available for products, customers, and orders (but not refunds or cancellations). Please see "Enabling Batch Updates" above for details on configuration.
0.11.1 2018-05-14 * Fix for Customer address import issues causing some addresses to be cut off prematurely. If affected, install the update, then ask ODP Support to reimport customers for you.
0.11.0   Support Magento EE Full Page Cache
0.10.2   Fixed for WS-I compliance for python and .NET clients.
0.10.1   The initial data ingest will no longer fail if orders correspond to an invalid Magento store.
0.10.0   ODP works with Magento when WS-I mode is enabled.
0.9.0   In-stock information/quantity remaining is now provided for items each time they are purchased.
0.8.3   Orders now use base currency, rather than native currency.
0.8.2   Fix a regression in support for older PHP versions where the plugin would not work correctly.
0.8.1   Every API call to ODP now submits data via an encrypted connection.
0.8.0   Allow product/order/customer ids to be prefixed by a unique id to allow multiple magento instances to be pulled into a single ODP account.
0.7.2   For products, ODP now uses the "media URL" for an item, rather than the cached, rescaled version of an image.
0.7.1   Provide product brand information from the Magento manufacturer field.
0.7.0   Add support for generating unique coupon codes via ODP campaigns.
0.6.11   Fixed a potential problem with cart abandonment link handling.
0.6.10   * Support installs with php up to 7.1.2
* Fix a bug where cart abandonment required a static cart creation time (other Magento plugins can change the cart creation timestamp) resulting in problems with cart abandonment campaigns.
0.6.8   Backend order tracking now correctly handles orders that move directly from "pending" to "complete". Previously, because "processing" was skipped, the order purchase event was not being sent. This only applies if the "Track Orders on Frontend" option is turned off.
0.6.7   * Cart Abandonment links now work for installs with multiple servers.
* Orders are now tracked when the order moved into the "processing" state, rather than when it is created (only if the "Track Orders on Frontend" option is turned off).
0.6.6   * UTM parameters are passed along during abandoned cart redirects.
* Custom fields are now optionally returned on products.
* The plugin version number (0.6.6) is provided back to ODP when data is sent to ODP, to aid in debugging.
0.6.4   * Abandon cart links work more reliably with ODP Engage.
* Product images are now correctly imported into ODP.
0.6.2   Provide historical information about customer unsubscribe status upon customer ingest.
0.6.1   Bug fixes related to posting of backend orders and product entities..
0.6.0   * Default orders to be produced via the Magento backend, rather than relying on the post-order page fully loading.
* Fix an issue related to UTF-8 corruption in billing address which could cause lost orders for customers in foreign locales.
0.5.7   Allows cart abandonment to work for customers who are not logged into the system (but whose identities can be inferred through user stitching).
0.5.5   Minor bugfix related to producing errors instead of exceptions on missing image files.
0.5.4   Minor bugfix related to incorrect processing of purchases entered from the admin console.
0.5.3   Changed order tracking strategy to work more reliably with checkouts involving redirection to third party payment processors.
0.5.2   Capture image_url and description for product entities.
0.5.1   Provide information for shopping cart abandonment campaigns.
0.5.0   Support order cancellation and order refunds.
0.4.0   * New bulk retrieval API to streamline and generally improve the initial import process.
* Capture price for product entities.
* Capture associated Magento website, store, and store view on all events (and bulk imported orders) to aid in scoping and analysis.
0.3.2   Fixed order tracking bug that was causing multi-shipping checkouts to fail.
0.3.1   * Added safer handling of potentially missing internal data fields. If you are having trouble with the checkout process not completing, this should fix the issue.
* Explicitly reverts to anonymous mode upon customer logout.