Shopify Fulfillment Integration Overview

This guide provides basic information for integrating fulfillment integration between Mercury (Landmark’s WMS and TMS system) and the Shopify eCommerce platform. This includes the configuration requirements needed to have Mercury pull in relevant information to fulfill and ship orders placed through Shopify.

Landmark leverages a number of Shopify features in order to sync inventory and ensure the correct items are fulfilled.

Shopify Subscription Level

Mercury's integration assumes the client is on a Shopify Plus subscription due to Shopify's API rate limits.

Connection Requirement: Custom App

In order to connect Mercury to a Shopify store, create a custom app connection for Landmark using webhook version "2023-10", and then ensure the following permissions are configured:

• write_assigned_fulfillment_orders
• read_assigned_fulfillment_orders
• write_fulfillments
• read_fulfillments
• write_inventory
• read_inventory
• write_orders
• read_orders
• write_translations
• read_translations
• write_third_party_fulfillment_orders
• read_third_party_fulfillment_orders

Once the app connection is created, the Landmark integration manager assigned to the account will need the following details from the custom app:

• api_key
• api_password
• Shop url (e.g. shop_name.myshopify.com)

Landmark as a Fulfillment Service

Once Mercury is connected via the custom app, Mercury will automatically register as a new fulfillment service for a Shopify store and create a new associated location for fulfillment. Mercury leverages Shopify's fulfillment service and locations functionality in order to track what Landmark should fulfill for a given order and manage inventory.

To set up Landmark as the fulfillment service, you will need to verify 3 things: 

1. Make sure each product variant has a variant sku number and casing that matches the sku number in Mercury. SKUs are case sensitive with this integration

In this sample product variant page, you can see that a sku is entered into the Inventory section on the bottom-right of the screenshot. Note that the data here is from a test store and does not reflect real products or values.

2. Set the fulfillment service to be Landmark

The fulfillment service app in the following example is named "socal-1-shopify". Once connected you will see an "App Location" entry under Settings > Locations. Once Landmark is set up as a fulfillment service, assign product variants to the Landmark Location for fulfillment (bottom of the variant screen). 

3. Set inventory policy to be managed by Landmark

See the next section for more details.

Inventory Management

Once Landmark is set as the fulfillment service for a product variant, you will want to change the Inventory Policy in Shopify so that inventory will sync directly from Mercury. (This will remove the ability to modify inventory manually in Shopify.) Shopify will immediately query Mercury for available inventory once the Inventory Policy is updated for a particular product.

Note: There could be some initial discrepancies between the quantity in the product’s inventory section and the stock actually available in a Landmark warehouse. For example, if the initial quantity for a SKU is greater than 0 in Shopify but Landmark’s warehouse doesn't have the product on hand, a product could be incorrectly shown as available for purchase until the initial inventory level sync is complete.

After the initial query, Shopify initiates the inventory sync using the fetch_stock endpoint to resync the available inventory every hour (the frequency of this querying cannot be altered). Mercury responds to the fetch_stock from Shopify with on-hand quantity and then Shopify uses order states (e.g. unfulfilled orders) to calculate using this value and adjust the quantity of a product to what it believes is sellable. The adjustment gets logged as "inventory changed by Landmark", but Landmark itself doesn't actually adjust inventory values for SKUs in Shopify. Instead, the change is caused by Shopify updating the inventory based on the information it receives from Mercury. On the Mercury side, inventory information is updated to reflect when products sell through, new inventory arrives at warehouses, or warehouse staff perform manual adjustments.

Automated Fulfillment

Mercury will check for new orders to fulfill every 15 minutes and Mercury will pull in information for orders that meet the following 3 requirements:

1. Paid
2. Created over 15minutes ago; and within the last 2 weeks.
3. Assigned to Landmark for fulfillment in Shopify

At this time, Landmark recommends enabling Automated Fulfillment for a connected Shopify store. This will allow Shopify to automatically assign items for Landmark to fulfill.

If orders do not have fulfillments created in Shopify assigned to Landmark, then Mercury will be unable to pull required order information.

Tracking Information

Once Mercury has pulled down the fulfillment information for orders Shopify is updated with a Landmark Tracking Number and Tracking URL. After the order is picked and shipped the shipments in Shopify are updated to "fulfillment complete". This triggers the shipping confirmation emails to customers through Shopify if enabled.

Mercury does not pass additional tracking number information back to Shopify.

Order Edits and Cancellations

After importing the order details, Mercury does not sync additional order edits or cancellations. Mercury will wait a minimum of 15 minutes after order creation and payment for edits to be made in Shopify. Once an order is imported to Mercury (fulfillment opened in Shopify), any changes or order cancellations must be done manually in Mercury.

Shipping Method Mapping

As part of the integration, send the Landmark integration manager a list of what shipping methods will be made available to customers in Shopify. This information will allow Landmark to map the service selected by the customer to the relative Landmark delivery method.