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:candidateormerge: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:orderfrom 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.
-
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. - 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.
-
Merge. When the hold window ends, each group of two or more orders becomes one merged order named
MRG-<oldest order number>, taggedmerge:order. The original orders are taggedmerge:memberandmergedInto:<merged order>and stay unroutable. - 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.
- 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
- Navigate to Integrations and open Merge Engine.
- Under Merge Rules, click Add Merge rules. A new rule opens with the default values filled in.
- 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/. - Select a Matching strategy,
tagoraddress, and fill in the fields for that strategy, as described in Merge rule settings below. - Set the Hold window (minutes), Hold window counted from, and Maximum hold (minutes).
- Set the optional filters and options you need.
- Make sure Enabled is selected.
- 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.
- At 10:00, a customer places order 1001. The app holds it and tags it
merge:candidate. - 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.
- At 11:00, the window ends. The app creates merged order
MRG-1001with the items of both orders. Orders 1001 and 1002 are taggedmerge:memberandmergedInto:MRG-1001. - Your warehouse ships
MRG-1001in one package with tracking number 1Z999. - 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:
- 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. - Open the held order and add that tag.
- 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
- Navigate to Integrations and open Merge Engine.
- Clear Enabled on every merge rule, or remove the rules.
- Click Save.
- Wait until no order carries the
merge:candidatetag. This usually takes 5 minutes. - Wait until every merged order (tagged
merge:order) has shipped and its original orders show their fulfillments. - 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:ordertag, 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 taggedmerge:candidateormerge: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 carriesmerge:candidateand 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.
Comments
0 comments