Skip to main content
A Custom Integration lets you connect a store running on a platform Privy doesn’t have a native app for — a headless storefront, an in-house system, or any platform without a dedicated Privy integration. You send your orders to Privy through the Orders API, and Privy uses that data to power segmentation and automated flows, just like a native e-commerce integration.
A Custom Integration sends order data to Privy. To display on-site campaigns (popups, bars, flyouts) and track visitor behavior, also install your Privy code on your site — see Manual install.

​
Features of the integration

  • Send orders to Privy: report placed orders to Privy with the POST /v1/orders/placed endpoint. Each call is an idempotent upsert keyed on your order_id, so re-sending the same order updates it.
  • Trigger automated flows: a new order can start an Order Placed flow, and marking an order delivered can start an Order Received flow (see Flows below).
  • Segment by order activity: orders update each contact’s order history so you can build segments from it (see Segments below).
  • Attribute orders to a store: every Custom Integration has its own integration token, so orders are tied to the store they came from.

​
Setting up the integration

1

Add a Custom Integration

In Privy, go to Settings → Integrations Hub and add a Custom Integration. Enter a Store Name and Store URL, then connect. Privy generates an integration token for the store — copy it when it’s shown. You can return to the integration later and use Reveal to retrieve it again.
2

Create an API access token

Go to Settings → API and create an access token with the Write orders (orders_write) scope. You’ll send this as your API bearer token.
3

Send your orders

From your platform, call POST /v1/orders/placed with your access token as Authorization: Bearer <token> and your store’s integration token as the optional X-Privy-Integration-Token header. See the Order placed API reference for the full request and field list.

​
Segments currently available

Privy tracks order activity for each contact created or updated from your Custom Integration orders, so you can segment by:
  • Number of orders — e.g. first-time vs. returning customers.
  • First and most recent order date — e.g. win-back segments for customers who haven’t ordered recently.
These work alongside all standard contact attributes that aren’t tied to a specific platform — email and SMS subscription status, tags, sign-up source, and more.
Coming in future releases: lifetime spend (total spent) and product/collection-based segments aren’t available for Custom Integrations yet. We’ll continue adding to this list.

​
Flows currently available

You can start a flow from either of these order triggers:
  • Order Placed — starts when you send a new order to Privy. Supported trigger conditions: Order Value, Order Count, Purchased Product, and Purchased Variant.
  • Order Received — starts when an order is marked delivered (via the order’s shipment status on the Orders API).
Because a Custom Integration doesn’t sync a product catalog (yet), the Purchased Product and Purchased Variant conditions are entered as the product ID / variant ID you send in your order’s line_items — the same IDs you own in your own system.
Coming in future releases: the Purchased from Collection condition isn’t available for Custom Integrations yet (orders don’t carry product-collection data). We’ll continue adding more triggers and conditions.