Iterable Events Reference

UltraCart pushes activity to your Iterable project server-to-server, in real time. There is no storefront pixel or tag to install: once your API key is saved, UltraCart sends each event directly to Iterable's API as it happens. This page lists every event UltraCart can send, when it fires, and which configuration setting controls it, so you can build Journeys and segments against them.

Where to see events

Every send is written to your integration log with the Iterable event name as the action label:

Operations → Reporting → Integration Logs

Filter the Action column by an event name (for example updateCart or refund) to see every time UltraCart pushed that event. In Iterable, the same events land on the shopper's user profile and in their event history, where they become Journey triggers and segmentation criteria.

Events at a glance

Event (Iterable name)	Fires when	Controlled by
Purchase (purchase)	An order is placed, including a subscription signup and every rebill	On whenever the integration is configured
Initial Purchase (uc_initial_purchase)	An order is placed that is not a subscription rebill	Send Initial Purchase Events
Shipment (fulfilled)	An order ships	On whenever the integration is configured
Reviews (trackReviews)	An order ships (review-request data)	On whenever the integration is configured
Order Updated (orderUpdated)	An order is edited, or its status changes	Send Order Updated Events
Refund (refund)	A refund is issued on an order	Send Refund Events
Cart Abandoned (updateCart)	A cart is classified as abandoned	Send Return Cart Events
Auto Order lifecycle (uc_autoorder_*)	A subscription is created, renewed, paused, resumed, cancelled, a rebill fails, or a single item changes	Send Auto Order Lifecycle Events

The core commerce events (purchase, shipment, reviews) flow as soon as the integration is configured with a valid API key and the order has a valid email; they are not individually toggled. The remaining events each have their own checkbox on the Iterable configuration screen, so you can turn off any category you do not use.

Cart abandonment and the auto order (subscription) lifecycle each have their own detailed page: see Iterable Abandoned Cart Integration and Iterable Auto Order (Subscription) Events.

Profile fields on custom events

The purchase and cart abandoned events update the contact's profile in Iterable with their name, address and phone number. The other events on this page are Iterable custom events, which cannot update a profile. When one of them is the first thing Iterable receives for a customer, the profile it creates holds only an email address. This is most common with subscribers who signed up before you connected Iterable, whose first event is often a renewal, a failed payment or a cancellation.

Turn on Send Profile With Events on the Iterable configuration screen, and UltraCart updates the profile from the order just before it sends each of these events:

• Every auto order lifecycle event (uc_autoorder_*)
• Order Updated (orderUpdated)
• Refund (refund)
• Shipment (fulfilled)

The update carries the customer's name, address, phone number and, when they opted in to text messages on that order, smsOptIn. Blank values are never sent, so it only fills in missing details and never clears ones the profile already has. The setting is off by default because it adds one Iterable API call per event, and each update shows in your integration log as updateUser.

Campaign attribution

Iterable can credit a purchase to a campaign in two ways, chosen per campaign:

• Time-based attribution (Iterable's default): Iterable credits a purchase to the campaign the contact most recently received, if it arrives within that campaign's attribution period. You do not need to set anything up in UltraCart.
• Attribution by campaignId: Iterable only credits a purchase that names the campaign in its campaignId field. A purchase without one is never counted for that campaign, and Iterable cannot add it later.

For attribution by campaignId, UltraCart has to know which campaign the shopper clicked. The reliable way to tell it is with link parameters, which add the campaign and template IDs to every link in the message. Without them, a campaign set to attribution by campaignId reports no purchases, even when the orders came from its links.

Set up link parameters in Iterable

Do this for each email and SMS template whose campaigns use attribution by campaignId:

1. In Iterable, go to Content → Templates and open the template.

2. In the template's Details area, click Edit.

3. Check Link parameters and add these two parameters:

   Key	Value
   iterable_campaign_id	{{campaignId}}
   iterable_template_id	{{templateId}}

4. Save the template.

Iterable fills in the IDs when the campaign is sent, so a link lands on your site with something like ?iterable_campaign_id=1234567&iterable_template_id=9876543. Iterable does not add link parameters to proofs, so test with a real send to yourself. The template ID matters when a campaign runs an experiment, because each variation has its own template and Iterable needs it to credit the right one.

The links can point to your UltraCart StoreFront, to checkout, or to your own site, as long as that site runs UltraCart Analytics so the visit can be followed through to checkout.

UltraCart also recognizes these, so existing setups keep working:

• iterable_campaign and iterable_template, the names used in Iterable's Shopify guide.
• iterable_sms_campaign_id and iterable_sms_template_id.
• The UTM parameters Iterable adds to shortened SMS, RCS and WhatsApp links when you turn on UTM parameters for the template (utm_source=Iterable with the campaign ID in utm_campaign). These carry the campaign only, not the template.

How UltraCart decides which campaign to send

• The most recent click wins. If the shopper clicks links from two campaigns before ordering, the order is credited to the second.
• Within your attribution window. An order placed later than the window after the click carries no campaign. The window is 24 hours unless you change it (see below).
• Never on a rebill. A subscription renewal is not credited to the campaign that brought in the original order.
• One order per click. A click that led to an earlier order is not reused for the shopper's next one.

When an order qualifies, UltraCart sends campaignId and templateId on its Purchase, Initial Purchase, Shipment, Reviews, Order Updated and Refund events.

Choose the attribution window

With attribution by campaignId, Iterable applies no time limit of its own: it credits whichever campaign the purchase names. The window UltraCart uses is therefore the only one, so set it to match how your own reporting credits email.

Set Campaign attribution window on the Iterable configuration screen (Main Menu → Operations → Marketing → 3rd Party Email (tab) → Iterable) to any number of days from 1 to 30. It is 1 day (24 hours) until you change it, which matches the window Iterable uses for its own attribution cookies. A change applies to clicks already recorded, not only to new ones.

A longer window works best when your links point to your UltraCart StoreFront or checkout, because the click is recorded on the shopper's cart right away and stays there when they come back later. When a link lands on your own site, the click is carried to checkout only if the shopper gets there during that visit. If they leave and return days later, the order is not credited to the campaign.

Iterable's attribution cookies

In email-based projects, Iterable can also set attribution cookies when a contact clicks a link in an email, and UltraCart reads them. They only work when the link destination shares a root domain with your project's link tracking domain (for example, links from links.example.com to www.example.com), and browsers increasingly block them. Iterable recommends link parameters instead, and so does UltraCart.

Check what an order sent

Open the order's trackPurchase entry in the integration log. Above the request, a line records the decision, for example:

Attributed to Iterable campaign 1234567 (template 9876543).

or the reason no campaign was sent:

Not attributed to an Iterable campaign: no Iterable click was recorded for this order.

The other reasons are that the click was earlier than your attribution window allows, or that the order is a rebill.

---

Purchase (purchase)

UltraCart's most important event. It is a native Iterable commerce event, so it populates the shopper's purchase history and revenue in Iterable automatically.

Fires when: an order is placed. This includes a one-time order, the first order of a new subscription (signup), and every subscription rebill.

Useful fields:

• Order ID, order total, subtotal, shipping and handling, discounts, and currency
• Each item: SKU, name, price, quantity, categories, product image URL, and product page URL
• subscription — true when the order is part of a subscription (auto order)
• rebill — true when the order is a renewal rather than the original signup order
• couponCodes: the coupon codes applied to the order. The field is present only when at least one coupon was used, and it lists every code on the order (both customer-entered and automatically applied)

Build with it: post-purchase flows, receipts and thank-you emails, revenue reporting, and first-order-versus-renewal branching (using the subscription and rebill flags). See Iterable Auto Order (Subscription) Events for how those flags behave and how to keep one-time buyers out of subscriber journeys.

Initial Purchase (uc_initial_purchase)

The purchase event above fires on every order, including every subscription rebill. That is what you want for revenue reporting, but it causes trouble when you measure campaign conversions. A rebill that happens to land after a shopper clicks one of your campaigns is counted as a conversion for that campaign, so a subscription business can end up crediting campaigns with renewals the campaign had nothing to do with.

uc_initial_purchase carries the same order data as the purchase event but fires only on orders that are not rebills, so you can use it as a campaign conversion event and keep renewals out of the count.

Fires when: an order is placed that is not a subscription rebill. A one-time order qualifies, and so does the first order of a new subscription. A renewal does not.

Controlled by: the Send Initial Purchase Events checkbox, which is off by default. Turn it on in each UltraCart account where you want the event.

Useful fields: the same order data as the purchase event, including order ID, totals and currency, the item list with SKUs, names, prices and images, coupon codes, UTM values, the billing and shipping addresses, and the subscription flag. There is no rebill field, because this event only exists for orders that are not rebills.

Build with it: campaign conversion tracking that counts first purchases and ignores renewals.

Using it as a conversion event

An Iterable campaign counts conversions against whichever event you name in its Conversion Events setting, but it draws revenue and purchase metrics from purchase events whatever you choose there. Switching the conversion event therefore changes your conversion counts and leaves your revenue reporting untouched.

For each campaign where you want renewals excluded:

1. Open the campaign and find the Conversion Events setting.
2. Remove iterable_purchase.
3. Add uc_initial_purchase.

note

Enabling Send Initial Purchase Events does not change any numbers on its own. Until you change the conversion event on a campaign, that campaign keeps converting on purchases and keeps counting rebills.

uc_initial_purchase appears in the Conversion Events list only after Iterable has received at least one of them, so place a test order once you have enabled the checkbox.

If the campaign uses attribution by campaignId, also add link parameters to its template, or Iterable has no way to tie the initial purchase to it. See Campaign attribution.

Initial purchase event IDs

Iterable discards duplicate events by event ID, and each initial purchase carries an ID built from the order ID:

uc-evt-DEMO-1001-initialpurchase

Reprocessing an order through the integration therefore cannot count the same conversion twice.

Shipment (fulfilled)

Fires when: an order ships. The event is an order-level snapshot: it carries the full order and all tracking numbers on the order at the time it fired. If an order ships in more than one shipment, the event refreshes to the latest fulfillment state rather than creating duplicates.

Useful fields:

• Order ID and all tracking numbers for the order
• Each item: SKU, name, price, quantity, categories, image and product page URL
• subscription / rebill flags (same meaning as on the purchase event)
• couponCodes: the coupon codes applied to the order, the same field as on the purchase event

Build with it: "your order has shipped" notifications with tracking links, and delivery-based follow-ups.

Reviews (trackReviews)

Fires when: an order ships. It carries the data needed to request product reviews for what the shopper bought.

Useful fields: the ordered items (SKU, name, categories) and a review token used to build a review link.

Build with it: post-delivery review-request campaigns.

Order Updated (orderUpdated)

One event covers both order edits and status changes, with an updateType field so your Journey can branch on what happened.

Fires when: an order is edited (items or address changed) or its status transitions — for example to on hold, completed, rejected, fraud review, or pending clearance.

Controlled by: the Send Order Updated Events checkbox.

Useful fields:

• updateType — items_changed, address_changed, or status_changed
• For status changes: previous status, new status, a status reason, and the current order total
• For edits: previous and new totals, the updated item list, and the shipping address

Build with it: status-driven messaging (for example, an "order on hold — action needed" email), and confirmations when an order is edited.

Shipment transitions are intentionally not routed here — a shipment is its own fulfilled event (above), so you wire shipping notifications to fulfilled, not to orderUpdated.

Refund (refund)

Fires when: a refund is issued against an order (full or partial).

Controlled by: the Send Refund Events checkbox.

Useful fields:

• Original order ID and original order total
• refundNumber: the position of this refund in the sequence of refunds on the order, starting at 1
• Refund amount, refund type (full / partial), and a refund reason
• The refunded items (SKU, quantity, amount) for item-level refunds
• Remaining order total after the refund

Build with it: refund confirmation emails and post-refund win-back or feedback flows.

Refund event IDs

Iterable discards duplicate events by event ID, so each refund carries an ID built from the order ID and the refund number:

uc-evt-DEMO-1001-refund-r1
uc-evt-DEMO-1001-refund-r2

The number in the ID is the same value as the refundNumber field. If you match UltraCart events against your own records, you can rebuild the ID of any refund event you have received rather than deriving it yourself.

Because the number counts refunds on that order, two refunds of the same amount for the same items are treated as separate events instead of one.

note

The counter is stored on the order and starts at 1 for refunds issued on or after 18 August 2026. It counts refunds from that date rather than over the lifetime of the order, so an order that was refunded before then and refunded again afterward sends r1, even though that is not the first refund on the order.

The refund count is also stored on the order as the iterableRefundCount property, so you can see it alongside the rest of the order data.

Cart Abandoned (updateCart)

Fires when: UltraCart classifies a shopper's cart as abandoned, after the delay you set with the Abandon cart after setting.

Controlled by: the Send Return Cart Events checkbox.

This event has a dedicated walkthrough — including how to build the recovery Journey and use the return-to-cart link — on the Iterable Abandoned Cart Integration page.

Auto Order (Subscription) lifecycle (uc_autoorder_*)

When you sell subscriptions (auto orders), UltraCart sends a family of lifecycle events — created, renewed, paused, resumed, payment failed, cancelled, and single-item changes — so you can build welcome, renewal, dunning, and win-back journeys.

Controlled by: the single Send Auto Order Lifecycle Events checkbox (it covers the whole family).

These events, the subscription / rebill flags, and the Only Flag Subscription For Physical Items option are all covered on the Iterable Auto Order (Subscription) Events page.