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": "malformed_json",
"message": "The request body is not valid JSON."
}
}{
"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"
}
}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
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": "malformed_json",
"message": "The request body is not valid JSON."
}
}{
"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"
}
}Authorizations
Send either an API token or an OAuth access token as
Authorization: Bearer <token>. See the Authentication page for details.
Headers
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.
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
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.
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.
1001
Order grand total. Required.
95
ISO 4217 three-letter currency code. Required.
"USD"
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).
"2026-06-01T12:00:00Z"
Buyer's email. Used to find or create the associated contact.
At least one of email or phone is required.
"buyer@example.com"
Buyer's phone number. Loosely formatted input is accepted and normalized to E.164.
Required when accepts_sms_marketing is true.
"+12025550123"
Your external identifier for the customer.
"ext-42"
Order subtotal before tax, shipping, and discounts.
90
Discounts applied to the order.
Show child attributes
Show child attributes
Tax lines applied to the order.
Show child attributes
Show child attributes
Total number of items in the order.
2
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.
authorized, expired, paid, partially_paid, partially_refunded, pending, refunded, voided "paid"
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.
fulfilled, in_progress, on_hold, open, partially_fulfilled, pending, pending_fulfillment, request_declined, restocked, scheduled, unfulfilled "fulfilled"
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.
attempted_delivery, carrier_picked_up, confirmed, delayed, delivered, failure, in_transit, label_printed, label_purchased, out_for_delivery, picked_up, ready_for_pickup "delivered"
The products purchased.
Show child attributes
Show child attributes
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
Show child attributes
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
Show child attributes
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.
true
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.
true
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.
false
Response
Existing order updated.
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
Show child attributes
Was this page helpful?