> ## Documentation Index
> Fetch the complete documentation index at: https://help.privy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a Custom Integration

> Send order data to Privy from any e-commerce platform or custom storefront using the Public API.

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](/docs/api-reference/order-placed), and Privy uses that data to power segmentation and automated flows, just like a native e-commerce integration.

<Note>
  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](https://dashboard.privy.com/settings/widget) on your site — see [Manual install](/docs/learn/integrations/manual-install).
</Note>

## 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](#flows-currently-available) below).
* **Segment by order activity:** orders update each contact's order history so you can build segments from it (see [Segments](#segments-currently-available) 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

<Steps>
  <Step title="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.

    <video autoPlay muted loop playsInline src="https://mintcdn.com/privy/zbAawQwjlmzW7UR2/images/integrations/custom-integration-installation.mp4?fit=max&auto=format&n=zbAawQwjlmzW7UR2&q=85&s=70253afcc1d1aabf5fb719bc36453291" data-path="images/integrations/custom-integration-installation.mp4" />
  </Step>

  <Step title="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.

    <video autoPlay muted loop playsInline src="https://mintcdn.com/privy/zbAawQwjlmzW7UR2/images/integrations/api-acces-token-create.mp4?fit=max&auto=format&n=zbAawQwjlmzW7UR2&q=85&s=c1281eeaf2a234cc0d7401b95abe45df" data-path="images/integrations/api-acces-token-create.mp4" />
  </Step>

  <Step title="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](/docs/api-reference/order-placed) for the full request and field list.
  </Step>
</Steps>

## 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.

<Note>
  **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.
</Note>

## 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](/docs/api-reference/order-placed)).

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.

<Note>
  **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.
</Note>