How to set up product recommendations in email

Setting the Products block’s Source to Recommendations can rank products by Bestsellers, Back in stock, Price drop, New arrivals, Bought together, or Based on what they viewed, without you picking products or writing a catalog rule. See Get recommended products for every field this source adds. Three of those strategies need data from outside your catalog to work: Bestsellers reads your order history, and Bought together and Based on what they viewed read what shoppers have looked at and bought. This guide covers what to send so each strategy has something to rank.

Tip

Already sending PW_AbandonedCart and PW_OrderCreated for abandoned cart recovery? Keep reading. Bestsellers needs one more field on PW_OrderCreated that the abandoned cart guide doesn’t cover.

Before you begin

Make sure your account’s catalog has products in it. Go to Content → Product Catalog and connect a feed, import a CSV, or add products by hand. Learn how to populate your catalog.

Developer assistance needed

Sending the events below requires your development team’s help, unless your store integration already sends them for you. Please share this guide with them.

New accounts see the regular catalog first

Every strategy below needs history to accumulate before it can rank anything. Until then, the block shows the regular catalog instead. See the note under Get recommended products.

Which strategies need events

Three of the six strategies rank products from events you send; the other three rank directly off your catalog and need nothing from you.

Strategy	Needs events?	Data source
Back in stock	No	Catalog stock changes
Price drop	No	Catalog price changes
New arrivals	No	Catalog “added” date
Bestsellers (7/30 days)	Yes	PW_OrderCreated / PW_OrderUpdated with items
Based on what they viewed	Yes	Any event carrying a product ID. Order items also feed the pairs it ranks
Bought together	Yes	Any event carrying a product ID or order items, plus a device tag

A stock or price change in your feed, or the next scheduled sync, updates Back in stock, Price drop, and New arrivals automatically. Nothing to send for those three.

Bestsellers: add items to your order events

Bestsellers (7 days) and Bestsellers (30 days) rank products by how many units sold in that window. They read the items array on PW_OrderCreated and PW_OrderUpdated, specifically each item’s productId and quantity.

If you already send PW_OrderCreated to clear abandoned cart tags, that minimal call (just orderId) still clears the cart, but it gives Bestsellers nothing to count. Add the order’s line items to the same call:

{
  "request": {
    "hwid": "8f65b16df378e7a6bece9614e1530fb2",
    "application": "XXXXX-XXXXX",
    "event": "PW_OrderCreated",
    "attributes": {
      "orderId": "ORDER-10293",
      "items": [
        {
          "productId": "SKU-4821",
          "quantity": 1
        },
        {
          "productId": "SKU-5190",
          "quantity": 2
        }
      ]
    },
    "userId": "shopper@example.com"
  }
}

productId must match the ID your Product Catalog uses for that item, so Bestsellers can look up the product to show. Extra item fields (price, name, and so on) are ignored for this strategy. Only productId and quantity count toward the ranking. The event also needs orderId, because an order without it isn’t counted.

When an order changes, send PW_OrderUpdated with the same orderId and items. For each product in the event, the new quantity replaces the earlier one instead of adding to it. A product can go down to 1 unit this way, but not to zero:

• quantity of 0 or below: the product counts as 1 unit sold.
• Product left out of items: the product keeps the quantity from the last event that included it.

For example, a customer orders 2 units of a product and returns both. If you send PW_OrderUpdated with that product’s quantity set to 0, Bestsellers counts 1 unit for it instead of 2. If you drop the product from items, it still counts 2. No event removes a returned or cancelled product from Bestsellers. It stops counting only once the order falls outside the 7- or 30-day window.

Paid Shopify orders already count

If you use the Shopify integration:

• Every paid order arrives as PW_OrderCreated, with the Shopify order ID as orderId and items carrying productId and quantity. Paid orders count toward Bestsellers with nothing to add on your side.
• productId is the Shopify product ID, the same ID your catalog uses when it’s imported from Shopify.
• The integration doesn’t send PW_OrderUpdated, so Bestsellers counts the quantities from the original order and doesn’t reflect later edits, refunds, or cancellations.

Send quantity as a number

Use a real JSON number for quantity, not a quoted string. Pushwoosh stores each attribute value only in the type it was first declared or inferred with; a mismatched value is dropped silently, and postEvent still returns success. See Use the correct attribute types for the same caution on PW_AbandonedCart.

Bestsellers ranks by order history specifically. Views and cart activity don’t count. For a ranking that includes browsing and cart activity too, use Based on what they viewed or Bought together instead.

Based on what they viewed and Bought together: track product activity

Both strategies build from the same signal: events that carry a product ID. You don’t need a dedicated “product viewed” event name — any custom event sent via postEvent counts, as long as its attributes include one of these keys:

• A single product, as a top-level attribute: product_id, productId, productid, item_id, or sku.
• Multiple products, as a products array where each item has product_id, productId, id, or sku.

For example, fire your existing product-view event with a product ID attribute already on it:

{
  "request": {
    "hwid": "8f65b16df378e7a6bece9614e1530fb2",
    "application": "XXXXX-XXXXX",
    "event": "ProductViewed",
    "attributes": {
      "product_id": "SKU-4821",
      "category": "Audio"
    },
    "userId": "shopper@example.com"
  }
}

Based on what they viewed recommends products that go with what each shopper looked at recently. It works like this:

• Pushwoosh keeps the last 10 products each shopper sent events for, newest first. Only events with the product ID keys above add products to this list. Order items don’t.
• The block shows products paired with those recent products, using the same pairs as Bought together (see below). Orders count toward those pairs, so sending PW_OrderCreated with items improves this strategy too, but it isn’t required.
• Products the shopper already has in their recent list aren’t shown.
• The list is cleared 30 days after the shopper’s last product event. If a shopper has no recent products, or none of them has pairs yet, the block shows the regular catalog for them.

No product tag or other setup is needed.

Tip

If you use the Shopify integration, the storefront theme embed already sends PW_ProductViewed with a productId on every product page view — nothing to add on your side, as long as the Push Init Embed toggle is on (it’s off by default). See Storefront browsing events.

Bought together shows products that shoppers often pick alongside a given product. For example, for a phone, the block can show the cases and chargers that other phone shoppers also viewed or bought. The more shoppers interacted with both products, the higher the recommended one ranks.

Despite the name, purchases aren’t required. Views, cart events, and orders all count. The strategy reads:

• Every event that carries a product ID, using the keys listed above.
• The items array of PW_OrderCreated and PW_OrderUpdated. Other events’ items, including PW_AbandonedCart, aren’t read.

Pushwoosh pairs products like this:

• Two products form a pair when the same user sent events for both within the last 30 days. The events can be separate: the products don’t need to be in the same order.
• Pairs are counted within one application. Activity in your account’s other applications doesn’t count.
• The rankings are recalculated once a day, so new events affect them starting the next day.

Bought together needs one more thing: a Product tag, a device tag that holds the ID of the product to build recommendations for. Set the field’s name when you configure the strategy in the Products block (for example PW_LastViewedProductID), then keep that tag updated on each device. For example, set it to the product’s ID whenever the shopper views a product. Without the tag set on a recipient, the block falls back to the regular catalog for them.

Tag name rules

The tag name only accepts letters, digits, underscores, and spaces, since it has to be addressable in Liquid. See Bought together needs a Product tag.

Confirm your events are landing

Before you add the block, check that Pushwoosh is actually receiving the events above: go to Audience → Events, open the event you sent (PW_OrderCreated or the custom event carrying a product ID), and confirm recent hits show up. See Event statistics.

Note

An empty Products block can mean either “the events never arrived” or “not enough history has accumulated yet” (see the note above). Event statistics rules out the first cause before you chase the second.

Add the block to your email

Add a Products block to your email content, set Source to Recommendations, and pick a Strategy. See Get recommended products for every field in the settings panel. Click Refresh preview to check the canvas fills with real products before you send.