flowcommerce/flowconnector

Flow Connector

Integrating Magento 2 with Flow

Introduction

Magento 2 is a popular e-commerce platform that helps businesses build and manage their online storefront. The Flow Connector extension for Magento 2 lets you seamlessly manage all of your global sales challenges., _(*1)

In this guide, you will: - Install the Flow Connector extension - Initialize the Flow-Magento integration - Configure your integration options, _(*2)

Once this extension is installed, you can optionally: - Enable Flow Country Picker - Localize Magento catalog prices - Localize Magento cart prices and totals - Redirect international customers to Flow Checkout UI, _(*3)

Prerequisites

In order to successfully connect your Magento console to Flow, you'll need the following:, _(*4)

• A Flow account with:
  • An Active Experience with Shipping Tiers available
  • A Flow API key for use in the Magento Back Office setup
  • your Flow Organization ID, which can be found in your Flow Console URL. For example, https://console.flow.io/{ORGANIZATION_ID}/experiences
• A Magento installation with:
  • Version 2.4.2 or greater
  • Magento Open Source (CE), Magento Commerce using on-prem (EE), or Magento Commerce on Cloud (ECE)
  • Shell access and permission to run command line tools
  • Crons enabled

Now, lets get started with the install process., _(*5)

Step 1 — Install extension

First, require the latest version of flowcommerce/flowconnector in the require section of Magento's composer.json:, _(*6)

"require": {
    "flowcommerce/flowconnector": "^{VERSION}"
}

Then, use composer to get the latest versions of dependencies and update your composer.lock file. Please note that all commands in this guide will be run using the Magento application root as the working directory:, _(*7)

$ composer update

Then, use composer to resolve dependencies and install the Flow Connector into your vendor directory:, _(*8)

$ composer install

Finally, use Magento's command line tool to complete the installation by updating your database schema and clearing your compiled code and cache:, _(*9)

$ php bin/magento setup:upgrade

Now, we are going to connect your Flow organization to your Magento store view., _(*10)

Step 2 — Connect Magento to Flow

First, login to your Magento Back Office. From the left hand menu, click on Stores -> Configuration. Change the Scope to your store (or default store if you only have one) and select Flow Commerce -> Connector Settings., _(*11)

Then, enable the connector and fill out your Flow Organization ID, Flow API Key, and Save Config., _(*12)

Then, we will use the settings we just configured to register webhooks for importing orders from Flow, register Sync Streams, and prepare Flow's catalog to sync Magento's catalog attributes:, _(*13)

$ php bin/magento flow:connector:initialize

A Sync Stream is a Flow service which tracks data syncing between two parties, in this case Flow and Magento 2. For more detail about how Flow Webhooks work please refer to this guide: Flow Webhook, _(*14)

Then, enqueue your Magento catalog to be synced:, _(*15)

$ php bin/magento flow:connector:catalog-enqueue

Finally, synchronize your Magento catalog:, _(*16)

$ php bin/magento flow:connector:catalog-sync

This extension also automatically syncs product information to Flow in two ways:, _(*17)

1. Product creations, updates, and deletes are queued with an observer. This queue is processed with a cron task every minute, with additional workers spawned every minute the queue is not empty.
2. A cron task that syncs the entire product catalog to Flow. By default, this syncs twice per day for production Flow organizations only.

Now, we are going to configure the remaining integration options available in the Magento Back Office to suit your business and technical requirements., _(*18)

Step 3 — Configure the integration

Login to your Magento Back Office. From the left hand menu, click on Stores -> Configuration. Change the Scope to your store (or default store if you only have one) and select Flow Commerce -> Connector Settings. This is a list of the extension configuration options available:, _(*19)

Enabled

This toggle controls the enabled status of the entire extension. When the Enabled option is set to "No", all functionality of the Flow Connector is disabled., _(*20)

Organization Id

This text field indicates which Flow organization should be integrated with the current store in Magento. This is a required field., _(*21)

API Token

This text field indicates the Flow organization secret API key which is used for authorization and communication with Flow's API. This is a required field., _(*22)

Checkout Base Url

This text field indicates the base url which is used for redirection to Flow Checkout UI. The value provided must have a CNAME DNS record mapped to https://checkout.flow.io/ which must be validated by Flow. By default, this field has no value and checkout redirection to Flow uses the standard https://checkout.flow.io/., _(*23)

Redirect to Flow Checkout

This toggle controls an automated redirection of international users to Flow Checkout UI via controller interception. At this point of redirect, Magento's cart is converted to a Flow order, including item discounts if enabled, and the user is sent Flow Checkout UI to complete their purchase. Following this purchase, webhooks are sent from Flow back to Magento to import the order data and empty the user's Magento cart. It is recommended that you select "Yes" for ease and consistency of the integration. This field defaults to "No"., _(*24)

Alternatively, you can use the same functionality as the automated path to build a valid Flow order by sending users to the redirect controller manually {BASE_URL}/flowconnector/checkout/redirecttoflow?country=FRA or implement your own integration by following this guide: Flow Checkout UI, _(*25)

For more information on customizing Flow Checkout UI please refer to this guide: Customizing Checkout UI., _(*26)

Support Magento Discounts

Discounts are calculated and applied according to the rules of your Magento store's base currency and applied as a percentage of the line item row total. Magento discounts applied to shipping costs are not applied to Flow orders. This field defaults to "Yes"., _(*27)

Create Invoice

This dropdown indicates how invoices are imported in Magento from Flow: - To create a Magento invoice at the point payment is captured in Flow, select "When Captured in Flow". - To create a Magento invoice at the point a shipping label is generated in Flow, select "When Shipped in Flow". - To never create a Magento invoice based on Flow order activity, select "Never"., _(*28)

Send invoice email

This toggle controls how invoice emails are triggered by Flow order activity. Selecting "Yes" enables invoice emails to be sent automatically after they are created in Magento. This option is dependent on "Create Invoice" being enabled as well. This toggle defaults to "Yes"., _(*29)

Create Shipment

This dropdown indicates how shipments are imported in Magento from Flow: - To create a Magento shipment at the point a shipping label is generated in Flow, select "When Shipped in Flow". - To never create a Magento shipment based on Flow order activity, select "Never"., _(*30)

Send shipment email

This toggle controls how shipment emails are triggered by Flow order activity. Selecting "Yes" enables shipment emails to be sent automatically after they are created in Magento. This option is dependent on "Create Shipment" being enabled as well. This toggle defaults to "Yes"., _(*31)

Enable Webhook Validation

This toggle controls the use of a secret key which is generated to protect Magento from receiving unauthorized webhooks. Selecting "No" is not recommended because it could allow other parties besides Flow to trigger Flow related functionality such as generating or altering order data. This toggle defaults to "Yes"., _(*32)

Enable Country Picker

This toggle controls the initialization of the Flow Country Picker. By default, the Flow Country Picker is included via Magento layout xml to the header panel and receives default styling and options. This toggle defaults to "Yes"., _(*33)

Alternatively, you can customize the initialization options by following our custom integration guide: Flow Country Picker., _(*34)

Enable Catalog Price Localization

This toggle controls the initialization of catalog price localization. This feature involves server-side API calls to Flow prior to page load as well as JavaScript mixins to complete the visual integration with catalog items. Selecting "Yes" will enable Flow API calls on Magento cache-miss events for product blocks to get all localized prices for this product dynamically. In this way, it loads the cache with every Flow experience price available to expedite page load time. When the browser page loads, JavaScript mixins are used to determine which prices should be shown to the user based on their geolocated IP address or Flow Country Picker selection. This toggle defaults to "Yes"., _(*35)

Alternatively, you can implement your own customized price localization solution by refering to our custom integration guide: Flow.js Product Localization, _(*36)

Enable Preload Localized Catalog Cache

This toggle controls whether or not server-side API calls will be used to preload localized experience pricing into Magento's page cache. This feature trades longer times on product cache-miss for a faster time to localized pricing. For this reason, it works best with a low amount of experiences and/or when paired with thorough and periodic cache warming. This toggle defaults to "No"., _(*37)

Maximum Time to Hide Catalog Prices

This text field controls the amount of time in milliseconds that catalog prices will remain hidden while waiting for the JavaScript mixins to determine which prices are to be displayed. This is a valuable tool to prevent the base currency price from displaying briefly before the local currency is displayed to the user. It is recommended to use a value of "5000" which means that regardless of the length of time it takes for the page to load, prices will never remain hidden by Flow for longer than 5 seconds. This field accepts integers and defaults to 0., _(*38)

Enable Cart Localization

This toggle controls the initialization of cart localization. This feature employs JavaScript mixins to observe international cart updates and localizes their amounts to match the local currency of the user. This localization occurs on both the core Magento minicart and dedicated cart page. This toggle defaults to "Yes"., _(*39)

Alternatively, you can implement your own customized price localization solution by refering to the documentation: Flow.js Cart Localization, _(*40)

Maximum Time to Hide Carts

This text field controls the amount of time in milliseconds that cart prices will remain hidden while waiting for the JavaScript mixins to localize the Magento cart to a valid Flow open order. This is a valuable tool to prevent the base currency cart totals from displaying briefly before the local currency is displayed to the user. It is recommended to use a value of "5000" which means that regardless of the length of time it takes for the page to load, cart totals will never remain hidden by Flow for longer than 5 seconds. This field accepts integers and defaults to 0., _(*41)

Enable Local Payment Methods on PDP

This toggle controls display of the local payment method logos which are available in Flow Checkout UI on the PDP. This is injected via the layout reference container "product.info.type" which appears on catalog product view pages (PDP). This toggle defaults to "Yes"., _(*42)

Alternatively, you can implement your own solution by refering to the documentation: Display Payment Method Logos, _(*43)

Enable Default Estimated Shipping Window on PDP

This toggle controls display of the estimated shipping window for the default shipping option on the PDP. This is injected via the layout reference container "product.info.type" which appears on catalog product view pages (PDP). This toggle defaults to "Yes"., _(*44)

Alternatively, you can implement your own solution by refering to the documentation: Display Delivery Window, _(*45)

Enable Tax and Duty Messaging

This toggle controls display of local tax and duties for all catalog item priceboxes. This toggle defaults to "Yes"., _(*46)

Alternatively, you can implement your own solution by refering to the documentation: Display Tax and Duty, _(*47)

Enable Daily Catalog Sync

This toggle controls the automatic enqueue of all skus daily at 1:15AM (timezone is dependent on your server configuration). Items will still be synced when their data has been updated and when using the flow:connector:catalog-sync shell command. This toggle defaults to "No"., _(*48)

Enable Regular Pricing Override

This toggle controls whether to use final_price or regular_price when syncing item prices with Flow and for Flow Checkout UI. The connector will always sync all available Magento item prices as additional attributes. This toggle defaults to "No"., _(*49)

Shell Commands Available

Save product attributes needed for catalog integration to Flow:, _(*50)

$ php bin/magento flow:connector:catalog-attributes-save

Sync queued items to Flow catalog:, _(*51)

$ php bin/magento flow:connector:catalog-sync

Sync missing orders from Flow to Magento:, _(*52)

$ php bin/magento flow:connector:order-sync

Enqueue all products for sync to Flow catalog:, _(*53)

$ php bin/magento flow:connector:catalog-enqueue

Remove Flow cron tasks older than 5 minutes and still marked as running:, _(*54)

$ php bin/magento flow:connector:cron-cleanup

Initialize integration with Flow. Includes webhook registration, sync stream registration, attributes creation, inventory center key fetching, and creating secret for webhook payload verification:, _(*55)

$ php bin/magento flow:connector:initialize

Fetch inventory center keys for all store views where flowconnector is configured:, _(*56)

$ php bin/magento flow:connector:center-fetch

Sync inventory queue to Flow. Warnings may be logged for items which are configured to not track inventory:, _(*57)

$ php bin/magento flow:connector:inventory-process

Enqueue all products for sync to Flow inventory:, _(*58)

$ php bin/magento flow:connector:inventory-sync

Process recieved Flow webhook events:, _(*59)

$ php bin/magento flow:connector:webhook-process

Register or update existing webhooks with Flow:, _(*60)

$ php bin/magento flow:connector:webhook-register

Create secret for webhook payload verification:, _(*61)

$ php bin/magento flow:connector:webhook-update

Extending Functionality

This extension dispatches several events that observers can listen to:, _(*62)

• An event is dispatched when a webhook event is received from Flow.
  • List of event types can be found in the Model/WebhookManger/EndpointsConfiguration.php class.
  • The event name is Flow\FlowConnector\Model\WebhookEvent::EVENT_FLOW_PREFIX + the event type.
• An event is dispatched after a webhook event is processed.
  • List of event types can be found in the Model/WebhookManger/EndpointsConfiguration.php class.
  • The event name is Flow\FlowConnector\Model\WebhookEvent::EVENT_FLOW_PREFIX + the event type + Flow\FlowConnector\Model\WebhookEvent::EVENT_FLOW_SUFFIX_AFTER.
• An event is dispatched after a product has been synced to Flow.
  • The event name is Flow\FlowConnector\Model\Sync\CatalogSync::EVENT_FLOW_PRODUCT_SYNC_AFTER.
• An event is dispatched if the customer changed their email address during Flow Hosted Checkout.
  • The event name is Flow\FlowConnector\Model\WebhookEvent::EVENT_FLOW_CHECKOUT_EMAIL_CHANGED.

Conclusion

Congratulations, your Magento 2 store is now integrated with Flow via the Flow Connector extension! Please contact a Flow representative to review your Flow organization settings and test the integration thoroughly prior to launching with live customers. When entering an international Flow experience you should see all product prices in the local currency and clicking checkout anywhere on the site should send you to Flow Checkout UI. Since Flow Checkout UI is hosted by Flow and is external to your Magento store, you may also want to host CSS and JS files which a Flow representative can help import to your Flow Checkout UI page load for branding and analytics consistency purposes., _(*63)