Order placed

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": "buyer@example.com",
  "phone": "+12025550123",
  "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"
}
'

import requests

url = "https://api.privy.com/v1/orders/placed"

payload = {
    "order_id": 1001,
    "email": "buyer@example.com",
    "phone": "+12025550123",
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    order_id: 1001,
    email: 'buyer@example.com',
    phone: '+12025550123',
    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'
  })
};

fetch('https://api.privy.com/v1/orders/placed', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.privy.com/v1/orders/placed",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'order_id' => 1001,
    'email' => 'buyer@example.com',
    'phone' => '+12025550123',
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.privy.com/v1/orders/placed"

	payload := strings.NewReader("{\n  \"order_id\": 1001,\n  \"email\": \"buyer@example.com\",\n  \"phone\": \"+12025550123\",\n  \"customer_id\": \"ext-42\",\n  \"subtotal\": 90,\n  \"discounts\": [\n    {\n      \"code\": \"SAVE10\",\n      \"amount\": 10\n    }\n  ],\n  \"tax_lines\": [\n    {\n      \"title\": \"VAT\",\n      \"amount\": 5\n    }\n  ],\n  \"total\": 95,\n  \"currency\": \"USD\",\n  \"total_items\": 2,\n  \"financial_status\": \"paid\",\n  \"fulfillment_status\": \"fulfilled\",\n  \"shipment_status\": \"delivered\",\n  \"line_items\": [\n    {\n      \"sku\": \"SKU-1\",\n      \"quantity\": 2,\n      \"price\": 45\n    }\n  ],\n  \"billing_address\": {\n    \"first_name\": \"Janet\",\n    \"last_name\": \"Biller\",\n    \"city\": \"Boston\",\n    \"state_code\": \"MA\",\n    \"country_code\": \"US\",\n    \"postal_code\": \"02118\"\n  },\n  \"shipping_address\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Shopper\",\n    \"city\": \"Boston\",\n    \"state_code\": \"MA\",\n    \"country_code\": \"US\",\n    \"postal_code\": \"02118\"\n  },\n  \"accepts_email_marketing\": true,\n  \"accepts_sms_marketing\": true,\n  \"order_date\": \"2026-06-01T12:00:00Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.privy.com/v1/orders/placed")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"order_id\": 1001,\n  \"email\": \"buyer@example.com\",\n  \"phone\": \"+12025550123\",\n  \"customer_id\": \"ext-42\",\n  \"subtotal\": 90,\n  \"discounts\": [\n    {\n      \"code\": \"SAVE10\",\n      \"amount\": 10\n    }\n  ],\n  \"tax_lines\": [\n    {\n      \"title\": \"VAT\",\n      \"amount\": 5\n    }\n  ],\n  \"total\": 95,\n  \"currency\": \"USD\",\n  \"total_items\": 2,\n  \"financial_status\": \"paid\",\n  \"fulfillment_status\": \"fulfilled\",\n  \"shipment_status\": \"delivered\",\n  \"line_items\": [\n    {\n      \"sku\": \"SKU-1\",\n      \"quantity\": 2,\n      \"price\": 45\n    }\n  ],\n  \"billing_address\": {\n    \"first_name\": \"Janet\",\n    \"last_name\": \"Biller\",\n    \"city\": \"Boston\",\n    \"state_code\": \"MA\",\n    \"country_code\": \"US\",\n    \"postal_code\": \"02118\"\n  },\n  \"shipping_address\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Shopper\",\n    \"city\": \"Boston\",\n    \"state_code\": \"MA\",\n    \"country_code\": \"US\",\n    \"postal_code\": \"02118\"\n  },\n  \"accepts_email_marketing\": true,\n  \"accepts_sms_marketing\": true,\n  \"order_date\": \"2026-06-01T12:00:00Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.privy.com/v1/orders/placed")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"order_id\": 1001,\n  \"email\": \"buyer@example.com\",\n  \"phone\": \"+12025550123\",\n  \"customer_id\": \"ext-42\",\n  \"subtotal\": 90,\n  \"discounts\": [\n    {\n      \"code\": \"SAVE10\",\n      \"amount\": 10\n    }\n  ],\n  \"tax_lines\": [\n    {\n      \"title\": \"VAT\",\n      \"amount\": 5\n    }\n  ],\n  \"total\": 95,\n  \"currency\": \"USD\",\n  \"total_items\": 2,\n  \"financial_status\": \"paid\",\n  \"fulfillment_status\": \"fulfilled\",\n  \"shipment_status\": \"delivered\",\n  \"line_items\": [\n    {\n      \"sku\": \"SKU-1\",\n      \"quantity\": 2,\n      \"price\": 45\n    }\n  ],\n  \"billing_address\": {\n    \"first_name\": \"Janet\",\n    \"last_name\": \"Biller\",\n    \"city\": \"Boston\",\n    \"state_code\": \"MA\",\n    \"country_code\": \"US\",\n    \"postal_code\": \"02118\"\n  },\n  \"shipping_address\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Shopper\",\n    \"city\": \"Boston\",\n    \"state_code\": \"MA\",\n    \"country_code\": \"US\",\n    \"postal_code\": \"02118\"\n  },\n  \"accepts_email_marketing\": true,\n  \"accepts_sms_marketing\": true,\n  \"order_date\": \"2026-06-01T12:00:00Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "order_id": 1001,
    "source": "api",
    "email": "buyer@example.com",
    "phone": "+12025550123",
    "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"
  }
}

{
  "data": {
    "order_id": 1001,
    "source": "api",
    "email": "buyer@example.com",
    "phone": "+12025550123",
    "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,
    "integration": {
      "store_name": "My Store",
      "store_url": "https://mystore.example.com"
    },
    "created_at": "2026-06-01T12:00:05Z",
    "updated_at": "2026-06-01T12:00:05Z"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Bearer token is missing or invalid"
  }
}

{
  "error": {
    "code": "insufficient_scope",
    "message": "Token does not have the required scope"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid",
    "details": [
      {
        "field": "email",
        "message": "is required"
      }
    ]
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

Orders

Order placed

Send an order to Privy when a customer completes a purchase.

Privy uses order_id to decide whether to create or update the order. The first request for an order_id creates the order and returns 201 Created. Later requests with the same order_id update it and return 200 OK. When updating an order, send its latest data. If you leave out an optional field, Privy keeps its existing value.

Privy links the order to a contact using email. If you do not send an email address, it uses phone instead. If no matching contact exists, Privy creates one.

accepts_email_marketing can subscribe the contact to email but cannot unsubscribe an existing contact. accepts_sms_marketing records an SMS opt-in only for newly created contacts and requires phone. It does not change the SMS consent of an existing contact.

To associate the order with a specific Custom Integration, include the optional X-Privy-Integration-Token header. See the header description below for setup instructions and fallback behavior.

Required scope: orders_write

POST

orders

placed

Order placed

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": "buyer@example.com",
  "phone": "+12025550123",
  "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"
}
'

import requests

url = "https://api.privy.com/v1/orders/placed"

payload = {
    "order_id": 1001,
    "email": "buyer@example.com",
    "phone": "+12025550123",
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    order_id: 1001,
    email: 'buyer@example.com',
    phone: '+12025550123',
    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'
  })
};

fetch('https://api.privy.com/v1/orders/placed', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.privy.com/v1/orders/placed",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'order_id' => 1001,
    'email' => 'buyer@example.com',
    'phone' => '+12025550123',
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.privy.com/v1/orders/placed"

	payload := strings.NewReader("{\n  \"order_id\": 1001,\n  \"email\": \"buyer@example.com\",\n  \"phone\": \"+12025550123\",\n  \"customer_id\": \"ext-42\",\n  \"subtotal\": 90,\n  \"discounts\": [\n    {\n      \"code\": \"SAVE10\",\n      \"amount\": 10\n    }\n  ],\n  \"tax_lines\": [\n    {\n      \"title\": \"VAT\",\n      \"amount\": 5\n    }\n  ],\n  \"total\": 95,\n  \"currency\": \"USD\",\n  \"total_items\": 2,\n  \"financial_status\": \"paid\",\n  \"fulfillment_status\": \"fulfilled\",\n  \"shipment_status\": \"delivered\",\n  \"line_items\": [\n    {\n      \"sku\": \"SKU-1\",\n      \"quantity\": 2,\n      \"price\": 45\n    }\n  ],\n  \"billing_address\": {\n    \"first_name\": \"Janet\",\n    \"last_name\": \"Biller\",\n    \"city\": \"Boston\",\n    \"state_code\": \"MA\",\n    \"country_code\": \"US\",\n    \"postal_code\": \"02118\"\n  },\n  \"shipping_address\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Shopper\",\n    \"city\": \"Boston\",\n    \"state_code\": \"MA\",\n    \"country_code\": \"US\",\n    \"postal_code\": \"02118\"\n  },\n  \"accepts_email_marketing\": true,\n  \"accepts_sms_marketing\": true,\n  \"order_date\": \"2026-06-01T12:00:00Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.privy.com/v1/orders/placed")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"order_id\": 1001,\n  \"email\": \"buyer@example.com\",\n  \"phone\": \"+12025550123\",\n  \"customer_id\": \"ext-42\",\n  \"subtotal\": 90,\n  \"discounts\": [\n    {\n      \"code\": \"SAVE10\",\n      \"amount\": 10\n    }\n  ],\n  \"tax_lines\": [\n    {\n      \"title\": \"VAT\",\n      \"amount\": 5\n    }\n  ],\n  \"total\": 95,\n  \"currency\": \"USD\",\n  \"total_items\": 2,\n  \"financial_status\": \"paid\",\n  \"fulfillment_status\": \"fulfilled\",\n  \"shipment_status\": \"delivered\",\n  \"line_items\": [\n    {\n      \"sku\": \"SKU-1\",\n      \"quantity\": 2,\n      \"price\": 45\n    }\n  ],\n  \"billing_address\": {\n    \"first_name\": \"Janet\",\n    \"last_name\": \"Biller\",\n    \"city\": \"Boston\",\n    \"state_code\": \"MA\",\n    \"country_code\": \"US\",\n    \"postal_code\": \"02118\"\n  },\n  \"shipping_address\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Shopper\",\n    \"city\": \"Boston\",\n    \"state_code\": \"MA\",\n    \"country_code\": \"US\",\n    \"postal_code\": \"02118\"\n  },\n  \"accepts_email_marketing\": true,\n  \"accepts_sms_marketing\": true,\n  \"order_date\": \"2026-06-01T12:00:00Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.privy.com/v1/orders/placed")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"order_id\": 1001,\n  \"email\": \"buyer@example.com\",\n  \"phone\": \"+12025550123\",\n  \"customer_id\": \"ext-42\",\n  \"subtotal\": 90,\n  \"discounts\": [\n    {\n      \"code\": \"SAVE10\",\n      \"amount\": 10\n    }\n  ],\n  \"tax_lines\": [\n    {\n      \"title\": \"VAT\",\n      \"amount\": 5\n    }\n  ],\n  \"total\": 95,\n  \"currency\": \"USD\",\n  \"total_items\": 2,\n  \"financial_status\": \"paid\",\n  \"fulfillment_status\": \"fulfilled\",\n  \"shipment_status\": \"delivered\",\n  \"line_items\": [\n    {\n      \"sku\": \"SKU-1\",\n      \"quantity\": 2,\n      \"price\": 45\n    }\n  ],\n  \"billing_address\": {\n    \"first_name\": \"Janet\",\n    \"last_name\": \"Biller\",\n    \"city\": \"Boston\",\n    \"state_code\": \"MA\",\n    \"country_code\": \"US\",\n    \"postal_code\": \"02118\"\n  },\n  \"shipping_address\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Shopper\",\n    \"city\": \"Boston\",\n    \"state_code\": \"MA\",\n    \"country_code\": \"US\",\n    \"postal_code\": \"02118\"\n  },\n  \"accepts_email_marketing\": true,\n  \"accepts_sms_marketing\": true,\n  \"order_date\": \"2026-06-01T12:00:00Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "order_id": 1001,
    "source": "api",
    "email": "buyer@example.com",
    "phone": "+12025550123",
    "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"
  }
}

{
  "data": {
    "order_id": 1001,
    "source": "api",
    "email": "buyer@example.com",
    "phone": "+12025550123",
    "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,
    "integration": {
      "store_name": "My Store",
      "store_url": "https://mystore.example.com"
    },
    "created_at": "2026-06-01T12:00:05Z",
    "updated_at": "2026-06-01T12:00:05Z"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Bearer token is missing or invalid"
  }
}

{
  "error": {
    "code": "insufficient_scope",
    "message": "Token does not have the required scope"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid",
    "details": [
      {
        "field": "email",
        "message": "is required"
      }
    ]
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

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

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"

string<email>

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

Example:

"buyer@example.com"

phone

string

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

Example:

"+12025550123"

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.

Available options:

authorized,

expired,

paid,

partially_paid,

partially_refunded,

pending,

refunded,

voided

Example:

"paid"

fulfillment_status

enum<string>

The order's overall fulfillment state (mirrors Shopify's OrderDisplayFulfillmentStatus). Stored on the order but does not affect delivery-based flow triggers — use shipment_status for that.

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 (mirrors Shopify's FulfillmentEventStatus). Setting this to delivered triggers any "Order Received" flows for the customer.

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

Show child attributes

accepts_email_marketing

boolean

Whether the buyer opted into email marketing. Subscribes the contact on signup; never unsubscribes an existing contact.

Example:

true

accepts_sms_marketing

boolean

Whether the buyer opted into SMS marketing. Requires phone. Records an SMS opt-in for newly created contacts only; existing contacts' SMS consent is left untouched.

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

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

Delete a contact Ingest an event

⌘I

API Reference

Contacts

Orders

Events

Order placed

Authorizations

Headers

Body

Response