New customer status

The $is_new_customer property on the Placed Order event tells Converge whether the order is a customer’s first purchase. It powers the New Customer Order derived event, the NewCustomerPurchase events forwarded to Meta, TikTok, and Reddit, and the customer_type (NEW vs. RETURNING) field on server-side Google Ads conversions.

​

What “new customer” means

A new customer is a profile whose current Placed Order is their first completed purchase from your store. It isn’t about whether the customer just registered an account, signed up for a newsletter, or is visiting for the first time. The only question is: have they bought from you before? That definition lives on the order, not the profile. A profile that was created last year but only places its first order today is a new customer on today’s order. From the next order onward, it isn’t.

​

Who sets the value

There are two paths, and they behave differently.

​

Prebuilt integrations: Converge sets it for you

If your Placed Order events come in through a prebuilt source like Shopify, BigCommerce, WooCommerce, or Firmhouse, Converge sets $is_new_customer automatically using the platform’s native new-customer signal.

​

Custom integrations: you set it

If you send Placed Order from a custom server-side webhook, a custom mobile app, or any source Converge doesn’t have a native integration for, you’re the one responsible for setting $is_new_customer. Your backend has authoritative order history.

​

How Converge fills it in if you don’t

If a Placed Order arrives without $is_new_customer, Converge falls back to its own history. It looks for prior Placed Order events on the same profile, matched on email. If a prior order exists, the customer is marked as returning. If not, they’re marked as new. This fallback is only as accurate as the history Converge has on file. Two situations can commonly come up:

• Short historical sync windows. If your prebuilt source was created with a start date that doesn’t cover the customer’s first order, that first order isn’t in Converge. A customer who bought in 2023 from a source synced from 2024 onward will look new on their next order.
• Identity changes. The fallback matches on email. A returning customer who places an order with a different email, a typo, or a separate account looks new to Converge, even though they aren’t to you.

For these reasons, passing the value explicitly is always more reliable than relying on the fallback.

​

Is the property required?

The spec marks $is_new_customer as required for the Placed Order event because passing it explicitly is the only way to get a reliable result. In practice, Converge won’t reject a Placed Order event that omits it — the fallback above kicks in instead.

​

Override rules

The rules for who wins between an explicit value and the fallback are simple:

• If you pass a value, Converge uses it. Passing true creates a New Customer Order event, even if Converge has seen that email before. Passing false doesn’t, even if Converge has no prior history for that customer.
• If you don’t pass a value, Converge uses the fallback.
• Converge never overwrites a value you explicitly passed. A common misconception, sometimes repeated by AI assistants, is that Converge recalculates $is_new_customer based on its own history regardless of what you send. It doesn’t. The explicit value wins.

​

A note on idempotency

Converge’s tracking API is idempotent on event_id. The first request to land for a given event_id is the one Converge persists; any later request with the same event_id is treated as a duplicate and dropped. That means if you send a Placed Order with $is_new_customer: false and then a few seconds later send a corrected event with $is_new_customer: true using the same event_id, the corrected value is dropped. Make sure the first event you send for an order has the right value, or use a new event_id if you genuinely need to record a new event. See deduplication for the full picture.

​

Quick reference

​

Related

• Placed Order spec
• Derived events
• Aliases
• Deduplication