Order placed

Report an order placed in your store.

This is an idempotent upsert keyed on order_id: the first call for an order_id creates the order and returns 201 Created; subsequent calls with the same order_id update it and return 200 OK. The order carries the full current state each time — omitted optional fields keep their previously stored value.

The order is associated to a contact by email (or, when no email is sent, by phone), creating the contact if needed.

accepts_email_marketing and accepts_sms_marketing drive the contact’s marketing consent — see the field descriptions for the exact semantics.

Optionally send the X-Privy-Integration-Token header to tie the order to a specific Custom Integration (see the header parameter below).

Required scope: orders_write

POST /orders/placed

Order placed

cURL

curl --request POST \
  --url https://api.privy.com/v1/orders/placed \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "order_id": 1001,
  "email": "[e-mail]",
  "phone": "[phone]",
  "customer_id": "ext-42",
  "subtotal": 90,
  "discounts": [
    {
      "code": "SAVE10",
      "amount": 10
    }
  ],
  "tax_lines": [
    {
      "title": "VAT",
      "amount": 5
    }
  ],
  "total": 95,
  "currency": "USD",
  "total_items": 2,
  "financial_status": "paid",
  "fulfillment_status": "fulfilled",
  "shipment_status": "delivered",
  "line_items": [
    {
      "sku": "SKU-1",
      "quantity": 2,
      "price": 45
    }
  ],
  "billing_address": {
    "first_name": "Janet",
    "last_name": "Biller",
    "city": "Boston",
    "state_code": "MA",
    "country_code": "US",
    "postal_code": "02118"
  },
  "shipping_address": {
    "first_name": "Jane",
    "last_name": "Shopper",
    "city": "Boston",
    "state_code": "MA",
    "country_code": "US",
    "postal_code": "02118"
  },
  "accepts_email_marketing": true,
  "accepts_sms_marketing": true,
  "order_date": "2026-06-01T12:00:00Z"
}
'

200

{
  "data": {
    "order_id": 1001,
    "source": "api",
    "email": "[e-mail]",
    "phone": "[phone]",
    "total_amount": "95.00",
    "currency_code": "USD",
    "placed_at": "2026-06-01T12:00:00Z",
    "financial_status": "paid",
    "fulfillment_status": "fulfilled",
    "shipment_status": "delivered",
    "customer_id": "ext-42",
    "total_items": 2,
    "accepts_email_marketing": true,
    "accepts_sms_marketing": true,
    "created_at": "2026-06-01T12:00:05Z",
    "updated_at": "2026-06-02T09:14:00Z"
  }
}

To trigger Privy Flows (such as Order Placed and Order Received) from orders sent to this endpoint, you must first connect a Custom Integration for your store. See Flows currently available for the supported triggers and conditions.

Authorizations

Authorization · string · header · required

Send either an API token or an OAuth access token as Authorization: Bearer <token>. See the Authentication page for details.

Headers

Privy-Account-Id · string

Target a subaccount instead of the main connected account. Pass a subaccount id from get_account's subaccounts list. Only direct subaccounts of the connected account are reachable — omit this for the main account itself.

X-Privy-Integration-Token · string

Optional. The integration token of a Custom Integration, sent in addition to the Authorization: Bearer token, to tie the order to that specific integration. Find it in your Privy dashboard under Settings → Integrations Hub → Connected, or generate a new one in the same Integrations Hub section under Custom Integration.

When omitted and the business has exactly one Custom Integration, the order is auto-tied to it; otherwise no integration is attributed. If the value doesn't match an active Custom Integration for your business, the request returns 422. This token only narrows attribution within the business already established by the bearer token — it is not a standalone credential.

Body

application/json

order_id, total, currency, and order_date are required on every call, plus at least one of email or phone. All other fields are optional; on an update, omitted optional fields keep their previously stored value.

order_id · integer<int64> · required

Your unique identifier for the order. Must be a positive integer (a digits-only string is also accepted). This is the idempotency key: the first call for an order_id creates the order, subsequent calls update it.

Example:

1001

total · number · required

Order grand total. Required.

Example:

95

currency · string · required

ISO 4217 three-letter currency code. Required.

Example:

"USD"

order_date · string<date-time> · required

ISO 8601 date-time the order was placed. Required. Expected to be in UTC (zero offset) — end the timestamp with Z (e.g. 2026-06-01T12:00:00Z).

Example:

"2026-06-01T12:00:00Z"

email · string<email>

Buyer's email. Used to find or create the associated contact. At least one of email or phone is required.

Example:

"[e-mail]"

phone · string

Buyer's phone number. Loosely formatted input is accepted and normalized to E.164. Required when accepts_sms_marketing is true.

Example:

"[phone]"

customer_id · string

Your external identifier for the customer.

Example:

"ext-42"

subtotal · number

Order subtotal before tax, shipping, and discounts.

Example:

90

discounts · object[]

Discounts applied to the order.

Show child attributes

tax_lines · object[]

Tax lines applied to the order.

Show child attributes

total_items · integer

Total number of items in the order.

Example:

2

financial_status · enum<string>

Payment status of the order, using Shopify's order financial-status vocabulary, which Privy treats as canonical across every source. Privy stores the value and reports it back; no flow or automation is triggered by it.

Available options: authorized, expired, paid, partially_paid, partially_refunded, pending, refunded, voided

Example:

"paid"

fulfillment_status · enum<string>

The order's overall fulfillment state — where the order sits in your store's fulfillment process (mirrors Shopify's OrderDisplayFulfillmentStatus). Stored with the order and echoed back, but it drives nothing: delivery-based flow triggers key off shipment_status instead.

Available options: fulfilled, in_progress, on_hold, open, partially_fulfilled, pending, pending_fulfillment, request_declined, restocked, scheduled, unfulfilled

Example:

"fulfilled"

shipment_status · enum<string>

Carrier delivery status of the shipment — where the parcel is (mirrors Shopify's FulfillmentEventStatus). This is the one order status Privy acts on: when a stored order's shipment_status becomes delivered, any "Order Received" flows start for the contact.

Only the change fires the flows. Sending delivered on the call that creates the order counts as a change; repeating it on a later call does not fire them again. initial_sync suppresses this along with the other real-time side effects.

Available options: attempted_delivery, carrier_picked_up, confirmed, delayed, delivered, failure, in_transit, label_printed, label_purchased, out_for_delivery, picked_up, ready_for_pickup

Example:

"delivered"

line_items · object[]

The products purchased.

Show child attributes

billing_address · object

A billing or shipping address. Stored and echoed back verbatim. When a new contact is created, its name is taken from the address — shipping first, billing as fallback — using first_name/last_name, or a single name field split on whitespace.

Show child attributes

shipping_address · object

A billing or shipping address. Stored and echoed back verbatim. When a new contact is created, its name is taken from the address — shipping first, billing as fallback — using first_name/last_name, or a single name field split on whitespace.

Show child attributes

accepts_email_marketing · boolean

Whether the buyer opted into email marketing as part of this order.

When true, Privy records email consent for the associated contact — including resubscribing a contact who had previously unsubscribed. Two limits apply: the order must have been placed within the last six months, so a backdated order_date older than that has no consent effect; and a suppressed contact stays suppressed.

When false, nothing is revoked. It never unsubscribes an existing contact and never weakens consent already on record — it only leaves a contact created by this call without email consent. The field has no effect on an order sent with a phone and no email.

Example:

true

accepts_sms_marketing · boolean

Whether the buyer opted into SMS marketing as part of this order. Requires phone.

Applies to newly created contacts only: the phone number becomes the contact's, and the opt-in is written to Privy's SMS consent log, which makes the contact textable immediately with no confirmation reply. An existing contact's SMS consent is never changed by this endpoint — use PATCH /v1/contacts/{id} for that.

Because this path bypasses Privy's own opt-in flows, you are responsible for having collected the consent in a TCPA-compliant manner. Unlike the Contacts endpoints, this one sends no welcome text.

Example:

true

initial_sync · boolean · default: false

Set to true for bulk historical imports. Suppresses real-time side effects (Flows and other automations, and campaign-revenue attribution) while still recording the order, associating the contact, and updating the contact's order_count, first_order_at, and last_order_at values.

Example:

false

Response

200

application/json

Existing order updated.

data · object

An order as persisted. Echoes back the fields you sent (column-backed fields normalized, the rest verbatim). Empty values are omitted from the response.

Show child attributes