Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt

Use this file to discover all available pages before exploring further.

Custom events give ad platforms more specific signals to optimize against. The most impactful is NC Purchase — it tells Meta to find buyers who’ve never purchased from you before, instead of optimizing toward repeat customers. Without it, Meta’s algorithm treats a first-time buyer and a fifth-time buyer as equally valuable conversions.

​
New customer purchase (NC Purchase)

NC Purchase fires only when an order comes from a customer with no prior Shopify order history. This enables NC CPA and NC ROAS reporting directly in Meta Ads Manager — two metrics that separate prospecting performance from retargeting performance.

​
Set up in Facebook

1

Wait for the first event

Once Upstack is live, the first NC Purchase event appears in Meta Events Manager within minutes for active stores. You need at least one event before you can proceed.See How to verify the NC Purchase event in Facebook Events Manager for a walkthrough.
2

Acknowledge the event

Go to Events Manager → find NC Purchase → Review → Acknowledge/Confirm. This tells Meta to start processing NC Purchase as a recognized event.
3

Create a custom conversion

In Events Manager, go to Custom Conversions → Create. Set the event to NC Purchase and give it a clear name (e.g., “Upstack NC Purchase”).See How to create and share NC Purchase custom conversion in Facebook for detailed steps.
You need Business Manager admin access (not just ad account admin) to create custom conversions. If you run ads through an agency ad account, switch the Events Manager view to your own Business Manager before creating the conversion.
4

Add reporting columns

In Ads Manager, add NC CPA and NC ROAS as columns in your reporting view. These metrics let you evaluate prospecting performance independently from retargeting.See How to add NC Purchase metrics and NC ROAS to Facebook Ads Manager for column configuration.
Attribution is forward-looking only — Meta does not backfill historical data for new event types. NC Purchase metrics start populating from the moment the custom conversion is created.
For the complete end-to-end walkthrough, see Complete guide to setting up NC Purchase metrics in Facebook Ads Manager.
Custom purchase events supplement the standard Purchase event — they don’t replace it. Keep standard Purchase active alongside the custom events so Meta’s baseline models still receive every order.
ScenarioRecommended event
General ROAS optimizationStandard Purchase
Scaling new customer acquisitionnc_purchase
Prospecting campaigns targeting cold audiencesnc_purchase
Retargeting campaigns for existing customersrc_purchase or standard Purchase
Brand awareness / top-of-funnelStandard Purchase (broader signal)
Measuring retention campaign performancerc_purchase
Allow a learning phase. When you switch an ad set from standard Purchase to nc_purchase, it re-enters Meta’s learning phase. Meta needs roughly 50 optimization events per week to exit learning, so start with your highest-spend or highest-volume campaign first if new-customer volume is low.Compare before shifting budget. Run nc_purchase-optimized campaigns alongside standard Purchase-optimized campaigns for 2–4 weeks and compare new-customer rate, CAC, and ROAS before committing.

​
Returning customer purchase (RC Purchase)

RC Purchase is the inverse of NC Purchase: it fires only when an order comes from a customer with existing Shopify order history. Together, the two events partition every order into acquisition vs. retention signals, which you can use separately in audience building, retargeting, and retention measurement. Classification uses the same Shopify-order-history check as NC Purchase — if the customer has zero prior completed orders, Upstack fires nc_purchase; if they have one or more, it fires rc_purchase. The standard Purchase event still fires for every order regardless of customer status, so baseline reporting is unaffected.

​
Why it matters

  • Build retargeting audiences that exclude first-time buyers. Feed rc_purchase into custom audiences of recent repeat customers for win-back campaigns, loyalty offers, or cross-sells.
  • Measure retention, not just acquisition. Treat rc_purchase volume and value as a direct signal of how well retention campaigns (email, SMS, paid retargeting) are performing.
  • Avoid over-indexing on repeat buyers in prospecting. Pairing rc_purchase with nc_purchase makes it obvious when a “Purchase-optimized” campaign is really just retargeting existing customers.

​
How it works

RC Purchase mirrors the NC Purchase setup in Meta — the only differences are the event name you select and the fact that the custom conversion represents returning customers.
1

Wait for the first event

Once Upstack is live, the first RC Purchase event appears in Meta Events Manager as soon as an existing customer places an order. You need at least one event before you can proceed.
2

Acknowledge the event

Go to Events Manager → find RC Purchase → Review → Acknowledge/Confirm so Meta starts processing it as a recognized event.
3

Create a custom conversion

In Events Manager, go to Custom Conversions → Create. Set the event to RC Purchase and give it a clear name (e.g., “Upstack RC Purchase”). Select Purchase as the category and leave the value field at its default so Meta uses the order value sent with the event.
You need Business Manager admin access (not just ad account admin) to create custom conversions. If you run ads through an agency ad account, switch the Events Manager view to your own Business Manager before creating the conversion.
4

Use it where retargeting or retention matters

Use the RC Purchase custom conversion as the optimization event for retargeting ad sets, or as a measurement column in Ads Manager alongside NC CPA / NC ROAS to see acquisition and retention performance side by side.
Enable nc_purchase and rc_purchase together. With both events running, every order is cleanly segmented into acquisition vs. retention — which means prospecting campaigns can optimize for nc_purchase, retargeting campaigns can optimize for rc_purchase, and the standard Purchase event still reports totals. Running only one of them leaves half the segmentation on the table.

​
Subscription events

For subscription brands, Upstack handles subscription events automatically. No manual setup is required.
EventWhen it firesSent to Meta?
Subscription InitialFirst subscription orderYes — counted as a purchase
Subscription RecurringRenewal ordersNo — excluded from Meta
Why recurring subscriptions are excluded from Meta: Sending renewal orders as purchase events tells Meta’s algorithm that existing customers are converting. This shifts optimization toward retargeting instead of prospecting — the algorithm learns to chase people who were going to buy anyway. Only the initial subscription triggers a purchase event so Meta stays focused on finding new subscribers.

​
Advanced configuration

If you sell across multiple product categories (e.g., apparel and skincare), Upstack can fire purchase events scoped to each category — apparel_purchase, skincare_purchase, and so on. This lets you create category-specific custom conversions in Meta and optimize ad sets for each product line independently.Contact the Upstack team to configure category-specific events for your store.
Not every order should feed back into Meta or Google’s optimization. Some sources would pollute your conversion data.To configure exclusions, go to Settings → Order Source Exclusions and select the sources you want to block:
  • TikTok Shop orders
  • Loop (returns/exchanges)
  • Matrixify (bulk imports)
  • Draft Orders
  • POS (in-store transactions)
Recurring subscription orders are excluded automatically. Initial subscription orders are sent — these represent genuine new-customer acquisitions.Sources only appear in the exclusion list if you have orders from them. If you don’t see a source listed, you haven’t had any orders from it yet.
Send more data to Facebook, not less. Even TikTok Shop orders help Meta find similar customers — the algorithm benefits from volume. Only exclude a source if the orders don’t represent real customer acquisition (e.g., wholesale imports) or would actively mislead optimization (e.g., POS sales unrelated to your online ad spend).

​
Next step

Configure contribution margin

Set up COGS, transaction fees, and marketing spend so the P&L dashboard reflects real profitability.

Complete NC Purchase setup guide

End-to-end walkthrough for NC Purchase, custom conversions, and reporting columns in Meta Ads Manager.

Verify NC Purchase events

Confirm NC Purchase events are arriving in Meta Events Manager and recognized correctly.

Connect a destination

Set up Meta CAPI as your first server-side destination for high-quality conversion events.

Verify end-to-end delivery

Confirm the complete pipeline works — from storefront event to destination delivery.