Merge Engine

The Merge Engine combines orders from one sales channel that go to the same recipient into a single merged order, so your warehouse picks, packs, and ships them in one package. When the merged order ships, the Merge Engine gives every original order its own fulfillment with the shared tracking number and only that order's items, and your sales channel receives the updates as usual.


Merge Engine and Order Aggregation Engine

Both engines combine orders, for different goals:

  • The Merge Engine combines orders to the same recipient so they ship in one package. Each original order still gets its own fulfillment, with the merged shipment's tracking number.
  • The Order Aggregation Engine combines many orders into one aggregated order to send fewer orders to systems such as NetSuite. It does not change how orders ship.

Do not use both engines on the same sales channel integration.


Before you begin

  • The Merge Engine integration is installed and Connected in your organization. The Merge Engine is in Beta and does not appear under Add Integration. Contact your Pipe17 representative to enable it.
  • Add an order automation that holds new orders from the sales channel for at least 15 minutes, using the Hold Order action. Without it, some orders route before the Merge Engine can hold them. See Setting Up Automation Engine.
  • No order automation triggers order routing on orders the Merge Engine holds. Add a condition to any automation with Trigger Order Routing so that it skips orders tagged merge:candidate or merge:member.
  • If you use the Order Exception Engine, set its Stuck Order Period longer than the rule's hold window. Otherwise held orders raise stuck-order exceptions.
  • If your sales channel is Shopify, keep Update Shopify fulfillment order structure to reflect Pipe17 shipments and Cancel order line items in Shopify for canceled shipping requests turned off in the Shopify integration settings.
  • If you export sales orders to an ERP or accounting system, exclude orders tagged merge:order from that export. Otherwise the merged order is booked a second time, on top of the original orders.

How it works

The Merge Engine runs every 5 minutes and works per merge rule. Each rule covers one sales channel integration.

  1. Hold. New orders from the sales channel that are not yet routed are held and tagged merge:candidate. Their routing is disabled while they wait.
  2. Match. The engine groups held orders that share the same merge key: the same merge tag value, or the same values in every address field the rule matches, depending on the rule's matching strategy. Orders in one group also share the shipping address, the currency and, by default, the shipping method.
  3. Merge. When the hold window ends, each group of two or more orders becomes one merged order named MRG-<oldest order number>, tagged merge:order. The original orders are tagged merge:member and mergedInto:<merged order> and stay unroutable.
  4. Ship. The merged order routes like any other order, and the warehouse ships it as one package. Only the merged order, its shipping request, and its fulfillment affect inventory.
  5. Split. When the merged order is fulfilled, every original order gets its own shipping request and fulfillment, with the same tracking number and only its own items. If the warehouse ships in several parcels, an original order can get several fulfillments. The sales channel connector posts them back to the channel.

An order with no match when its hold window ends is released to normal routing and tagged merge:released. A group waits at most the rule's Maximum hold, and any order still held an hour after that is released.

The merged order uses the oldest order's shipping address and shipping method, contains every item that requires shipping from every original order, and carries every original's gift note, shipping note, and order note. The order note lists the original orders it contains.


Add a merge rule

  1. Navigate to Integrations and open Merge Engine.
  2. Under Merge Rules, click Add Merge rules. A new rule opens with the default values filled in.
  3. Enter the Sales channel integration ID of the sales channel whose orders you want to merge. To find it, open that sales channel integration: the ID is the part of the page URL after /integrations/.
  4. Select a Matching strategy, tag or address, and fill in the fields for that strategy, as described in Merge rule settings below.

    Merge rule: sales channel integration ID, Enabled, matching strategy, and merge tag prefix

  5. Set the Hold window (minutes), Hold window counted from, and Maximum hold (minutes).

    Merge rule: hold window, maximum hold, and maximum orders per merged order

  6. Set the optional filters and options you need.

    Merge rule: tag filters, shipping methods, allowed countries, Walmart, location, and automations

  7. Make sure Enabled is selected.
  8. Click Save.

Add one rule per sales channel integration. Orders are only ever merged with orders from the same integration. If you add two rules for the same integration, the app uses the first valid one and lists the duplicate in the merge rules exception.

If a rule is invalid, the app does not use it and raises one exception on the Merge Engine integration that lists each problem. The exception clears when you fix the rule.


Merge rule settings

Setting What it does Default and limits
Sales channel integration ID (Required) The sales channel integration this rule applies to. Required. Cannot be the Merge Engine's own ID.
Enabled Turns the rule on or off. When you turn it off, orders the rule already holds are released within 5 minutes. On
Matching strategy How orders are matched. tag: orders with the same merge tag value are merged. address: orders with the same values in every Address fields to match are merged. tag
Merge tag prefix Tag strategy only. Orders tagged <prefix><value> with the same value are merged, for example mergeId:A123. Values are case-sensitive. An order with two different values is never merged. Orders with the same value but different shipping addresses become separate merged orders. mergeId:. Must end with :. Cannot start with merge: or mergedInto:.
Address fields to match Address strategy only. The fields that must be identical for orders to match. The app ignores letter case and extra spaces in every field, and periods and commas in names, company, and street lines. US ZIP codes are compared by their first 5 digits. fullName, company, address1, address2, city, stateOrProvince, zipCodeOrPostalCode, country, email. Must include address1, address2, zipCodeOrPostalCode, and country, plus at least one of fullName, firstName, lastName, company, email, or phone. Also allowed: city, stateOrProvince.
Required address fields Address strategy only. An order missing any of these fields is never merged. address1, zipCodeOrPostalCode, country. Must include those 3, and only fields that are also in Address fields to match.
Hold window (minutes) How long held orders wait for more orders from the same recipient. A lone order is released when its window ends. 660 (11 hours). From 1 to 2880.
Hold window counted from first: the window starts at the group's first order. last: the window restarts with each new order in the group, up to 5 minutes before the maximum hold. first
Maximum hold (minutes) The longest a group waits. When a group's window has ended but one of its orders is still on hold or being processed by an automation, the group waits up to this limit. Then the ready orders merge and the rest ship on their own. 1440 (24 hours). At least the hold window + 5.
Maximum orders per merged order The largest number of orders in one merged order. Larger groups are split into several merged orders, oldest orders first. A leftover group of one order ships on its own. 10. At least 2.
Only merge orders with these tags Only orders with at least one of these tags are held and merged. Empty (all orders)
Never merge orders with these tags Orders with any of these tags are never held or merged. Adding one of these tags to a held order releases it within 5 minutes. Empty
Merge orders with different shipping methods Off: only orders with the same shipping method are merged. On: orders with different shipping methods can be merged, and the merged order uses the oldest order's shipping method. Off
Allowed shipping countries Only orders shipping to these countries are merged. Enter 2-letter ISO country codes, for example US, CA. US
Allow shared tracking on Walmart Required to merge Walmart orders, because one tracking number is posted to several Walmart orders. Off
Ship merged orders from location Optional. Enter a location ID to send every merged order to that location, so it ships complete from one warehouse. Empty (normal routing)
Run automations on merged orders Off: merged orders skip order automations, because the original orders already ran them. On: order-updated automations run on merged orders before they route, for example to add a gift or insert. Off

Orders the Merge Engine never holds

An order is not held or merged when:

  • It comes from Amazon or eBay. These channels reject one tracking number on several orders.
  • It comes from Walmart and Allow shared tracking on Walmart is off.
  • It has more than one shipping destination.
  • It has no item that requires shipping, or it has a pickup, local delivery, or retail item.
  • It requires shipping labels.
  • It is already routed, or it arrived ready for fulfillment without an order hold.
  • It ships to a country that is not in Allowed shipping countries.
  • It carries a Never merge tag, or it lacks every Only merge tag.
  • Its hold window already ended when the engine first saw it.
  • It has no merge key: no merge tag (tag strategy), or a missing required address field or no recipient name, company, email, or phone (address strategy).

Example

Your rule for your online store uses the address strategy, a 60-minute hold window counted from the first order, and a 120-minute maximum hold.

  1. At 10:00, a customer places order 1001. The app holds it and tags it merge:candidate.
  2. At 10:25, the same customer places order 1002 to the same address with the same shipping method. The app holds it in the same group.
  3. At 11:00, the window ends. The app creates merged order MRG-1001 with the items of both orders. Orders 1001 and 1002 are tagged merge:member and mergedInto:MRG-1001.
  4. Your warehouse ships MRG-1001 in one package with tracking number 1Z999.
  5. Orders 1001 and 1002 each get a fulfillment with tracking number 1Z999 and their own items. Your online store shows both orders as shipped.

Release a held order early

To ship a held order on its own before it is merged:

  1. Make sure the rule has at least one tag in Never merge orders with these tags. Add one if it has none, for example no-merge.
  2. Open the held order and add that tag.
  3. Wait up to 5 minutes. The app releases the order to normal routing.

Routing a held order yourself also releases it, and it ships on its own. Do not remove the merge:candidate tag by hand: the Merge Engine adds it back and keeps holding the order.


After a merge

Once orders are merged, the merged shipment does not change by itself. While the merged order is still open, the app raises an exception on it when an original order is:

  • Canceled.
  • Edited, meaning its items or quantities changed. A new name, email, or phone number raises nothing.
  • Re-addressed, or given a different shipping method.
  • Routed or fulfilled on its own.

The app also raises an exception on the merged order when:

  • The merged order is canceled while its original orders are still held.
  • The warehouse ships it short or ships an item that does not belong to any original order.
  • The split to the original orders could not finish within 7 days.

When Run automations on merged orders is on, gifts or inserts that an automation adds to the merged order ship as usual and are not posted to the original orders.

Review these exceptions under Orders Requiring Attention on your dashboard and resolve them on the merged order. Never route an original order of a merged order on its own: it ships twice.


Turn off the Merge Engine

  1. Navigate to Integrations and open Merge Engine.
  2. Clear Enabled on every merge rule, or remove the rules.
  3. Click Save.
  4. Wait until no order carries the merge:candidate tag. This usually takes 5 minutes.
  5. Wait until every merged order (tagged merge:order) has shipped and its original orders show their fulfillments.
  6. Disable or uninstall the Merge Engine integration.

Do not disable the integration first. While the integration is disabled, in error, or uninstalled, the Merge Engine does not run: orders it still holds stay unroutable, and original orders of merged orders get no fulfillments or tracking.


Best practices

  • Match the hold window to how your customers order. A short window ships faster; a longer window catches more follow-up orders.
  • Use routing rules that filter on order source or the merge:order tag, not on the source integration. Merged orders belong to the Merge Engine integration and keep the oldest original order's order source.
  • Use Ship merged orders from location when you want merged orders to ship complete from one warehouse instead of being split by routing.
  • Test a new rule with a tag filter first: set Only merge orders with these tags to a test tag, tag a few orders, and check the result before you open the rule to all orders.

Limitations

  • Merging works within one sales channel integration only.
  • Amazon and eBay orders are never merged.
  • On Shopify, each original order sends its own shipping confirmation email to the customer.
  • When an original order changes after the merge, the app raises an exception; it does not rebuild or cancel the merged order for you.

Troubleshooting

  • Orders are not held
    Check that the rule is enabled, the Merge Engine integration is connected, and an order automation holds new orders from the sales channel for at least 15 minutes. Also check Allowed shipping countries (the default is US only), and that orders carry the merge tag (tag strategy) or every required address field (address strategy).
  • Orders to the same customer are not merged
    Check that both orders arrived within the hold window and share the same merge tag value or the same values in every Address fields to match, the same shipping address, the same currency, and the same shipping method (unless Merge orders with different shipping methods is on).
  • A held order shipped on its own, not merged
    An automation with Trigger Order Routing, or a manual route, released it. Make such automations skip orders tagged merge:candidate or merge:member.
  • The Merge Engine integration shows a merge rules exception
    A rule is invalid, a rule duplicates another rule for the same integration, or an automation released held orders. Read the exception, fix the rule settings or the automation, and save.
  • Orders stay unroutable or original orders get no tracking after you disabled the Merge Engine
    The integration was disabled too early. Enable the integration again, clear Enabled on every rule, wait until no order carries merge:candidate and every merged order has shipped, and then disable the integration.

Need Help?

If you need additional assistance:

  • Use Ask Pippen, our AI agent, located at the top of the platform page.
  • Submit a support request with as much relevant detail as possible. Learn how to submit a request.

We're here to help you succeed with your operations.

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.

Have more questions?
Submit a request
Share it, if you like it.