Platform Overview & Flow
Pricient provides an ultra-low latency, real-time reinforcement learning pricing engine. External merchants query Pricient for dynamic price discovery and report subsequent conversion events to continuously optimize yield and conversion rates.
limited_access privileges restricted only to pricing and checkout conversion calls).
End-to-End Integration Flow
Authenticate
Exchange Merchant API Key for a scoped 1-hour JWT token.
Query Price
Call /request_price/ on product page load to get the dynamic recommended price.
Customer Buys
Display the final price and capture customer transaction session.
Log Purchase
Call /make_purchase/ with request_id so the elastic pricing model learns from success.
Base URLs & Environments
All API requests must use HTTPS and send JSON bodies with standard HTTP headers.
| Environment | Base URL | Description |
|---|---|---|
| Production | https://api.pricient.co |
Live high-availability infrastructure with global multi-region low latency routing. |
Standard Request Headers
Content-Type: application/json
Accept: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>
Client-Side Web SDK (pricient-sdk.js)
The official Pricient JavaScript SDK provides automatic visitor identification, cookie-based session persistence, screen/viewport resolution capture, timezone resolution, and simplified price querying for web storefronts and browser apps.
pricient-sdk.js, it automatically handles persistent visitor IDs, resolves the shopper's real IP and location, parses their browser and device specifications, and captures local time without requiring you to manually pass telemetry in each call.
1. Include Script Tag
<script
src="https://api.pricient.co/static/sdk/pricient-sdk.js"
data-api-key="YOUR_MERCHANT_API_KEY"
data-merchant-id="YOUR_MERCHANT_UUID"
data-campaign-id="YOUR_CAMPAIGN_UUID"
async>
</script>
2. JavaScript Usage
// Initialize SDK (or use auto-initialized window.pricient)
const pricient = new Pricient({
apiKey: 'YOUR_MERCHANT_API_KEY',
merchantId: 'YOUR_MERCHANT_UUID',
campaignId: 'YOUR_CAMPAIGN_UUID'
});
// Optional: Identify a logged-in customer (defaults to persistent anonymous cookie)
pricient.identify('user_987654');
// Request dynamic price on product page
pricient.requestPrice({
productId: '0b74233e-80ef-4dfc-9b2b-3f4d8bd87eda'
}).then(res => {
console.log('Optimized dynamic price:', res.final_price);
document.getElementById('price-display').innerText = `$${res.final_price}`;
});
// Record a conversion when customer checks out
pricient.recordPurchase({
requestId: '681a0ed6-01c5-4b53-a84a-dbc879ef06f0',
revenue: 129.00,
quantity: 1
});
Integration Modalities: Web, Mobile, POS & Server Proxy
Pricient is engineered for any platform architecture—from browser single-page apps to native mobile apps, POS hardware (Toast, Square), and cloud server proxies (Spotify, Shopify apps).
Web Storefronts
Drop in pricient-sdk.js. Automatic cookie identity, browser telemetry, and client-side pricing.
Native Apps & POS
Direct REST calls from iOS, Android, or POS terminals. Real IP and User-Agent are auto-captured from TCP socket.
Server-to-Server
Forward X-Forwarded-For and User-Agent headers or pass explicit context fields in request body.
Server-to-Server Header Forwarding
If your backend server proxies pricing calls on behalf of shoppers, forward their client headers:
POST /request_price/
Authorization: Bearer <YOUR_ACCESS_TOKEN>
Content-Type: application/json
X-Forwarded-For: 198.51.100.42
User-Agent: Spotify/8.9.2 iOS/17.4 (iPhone15,2)
X-Pricient-Customer-Id: usr_98124
Automated End-User Telemetry Matrix
Pricient automatically extracts and indexes the following telemetry parameters for every pricing request to power bandit context vectors and analytics:
| Parameter | Description | Resolution Source |
|---|---|---|
ip |
Client IPv4 / IPv6 network address | Socket / CF-Connecting-IP / X-Forwarded-For |
location |
City, State, Country, Lat/Lon GPS coordinates | MaxMind GeoIP2 / Cloudflare Edge Geolocation |
timezone |
Customer or Physical Store IANA Timezone | Client Intl API / GeoIP / Store Config (e.g. Toast) |
local_time |
Exact local ISO timestamp, hour of day, and day of week | Timezone-aware clock evaluation |
device |
Device channel (ios, android, web) and hardware type |
User-Agent Parser & Client screen dimensions |
os & browser |
Granular OS & Browser name and version (iOS, macOS, Android, Windows, Chrome, Safari, SpotifyApp, ToastPOS) | Automated Regex & User-Agent Tokenizer |
rfm |
Customer Recency (days), Frequency (30-day count), Monetary (lifetime revenue) | Aggregated from past customer purchases in DB |
weather |
Real-time weather condition (Sunny, Cloudy, Rainy, Cold) | Open-Meteo Weather API cache |
1. Authentication (Token Exchange)
Obtain an access_token by passing your private merchant API Key. You can find or regenerate your API Key in your Merchant Dashboard Settings.
Request Parameters
| Field | Type | Description |
|---|---|---|
| api_key Required | string | Your private Merchant API Key generated from Pricient Merchant Settings. |
Code Examples
curl -X POST "https://api.pricient.co/get_public_token/" \
-H "Content-Type: application/json" \
-d '{
"api_key": "SCNJ8vDZOeNn87LXj8w8UU1d_89LWb7lWLAbmqIEU9M"
}'
const response = await fetch('https://api.pricient.co/get_public_token/', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
api_key: 'YOUR_MERCHANT_API_KEY'
})
});
const data = await response.json();
console.log('Access Token:', data.access_token);
// Store token for subsequent pricing requests
const axios = require('axios');
async function getAccessToken(apiKey) {
const { data } = await axios.post('https://api.pricient.co/get_public_token/', {
api_key: apiKey
});
return data.access_token;
}
import requests
url = "https://api.pricient.co/get_public_token/"
payload = {"api_key": "YOUR_MERCHANT_API_KEY"}
response = requests.post(url, json=payload)
data = response.json()
access_token = data.get("access_token")
print("Access Token:", access_token)
<?php
$ch = curl_init('https://api.pricient.co/get_public_token/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'api_key' => 'YOUR_MERCHANT_API_KEY'
]));
$response = curl_exec($ch);
$data = json_decode($response, true);
$accessToken = $data['access_token'];
?>
Response (200 OK)
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxLCJwZXJtcyI6ImxpbWl0ZWRfYWNjZXNzIiwiZXhwIjoxNzM1NzE4NDAwfQ.sZ7..."
}
2. Request Price (Single Product)
Queries the elastic pricing engine to retrieve the optimized price for a specific product item in a campaign.
Request Body Schema
| Field | Type | Description |
|---|---|---|
| context.merchant_id Required | UUID | Merchant UUID identifier. |
| context.campaign_id Required | UUID | Campaign UUID identifier containing the product. |
| context.product_id Required* | UUID | UUID of the Product (*or provide product_name). |
| context.customer_id Optional | string | Unique customer/visitor ID. If omitted, Pricient auto-resolves via cookie/anonymous UUID. |
| context.customer_ip Optional | string | Explicit client IP override for server proxies (or pass via X-Forwarded-For header). |
| context.customer_timezone Optional | string | Client IANA Timezone (e.g. America/New_York). Auto-resolved if omitted. |
| context.customer_device_channel Optional | string | Client platform channel (ios, android, web). Auto-detected from User-Agent if omitted. |
| context.customer_screen_resolution Optional | string | Customer screen dimensions (e.g. 1920x1080). Auto-captured by Web SDK. |
| context.customer_language Optional | string | Customer locale / browser language (e.g. en-US, es-ES). |
| context.customer_page_url Optional | string | Current product storefront URL. Auto-captured by Web SDK. |
| context.customer_referrer Optional | string | Referring URL / traffic source (e.g. https://google.com). |
| context.customer_user_agent Optional | string | Explicit User-Agent override for server proxies (or pass via User-Agent header). |
Code Examples
curl -X POST "https://api.pricient.co/request_price/" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"context": {
"merchant_id": "b64aa6bd-379c-4155-828e-ce7a3fa59f5b",
"campaign_id": "a69453b6-77ef-446d-808d-fe7f9738f01f",
"product_id": "0b74233e-80ef-4dfc-9b2b-3f4d8bd87eda",
"customer_id": "cust_sess_9a87d12f"
}
}'
const res = await fetch('https://api.pricient.co/request_price/', {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
context: {
merchant_id: "b64aa6bd-379c-4155-828e-ce7a3fa59f5b",
campaign_id: "a69453b6-77ef-446d-808d-fe7f9738f01f",
product_id: "0b74233e-80ef-4dfc-9b2b-3f4d8bd87eda",
customer_id: "cust_sess_9a87d12f"
}
})
});
const { request_id, final_price, original_price } = await res.json();
console.log(`Optimized price: $${final_price} (Original: $${original_price})`);
import requests
headers = {"Authorization": f"Bearer {access_token}"}
payload = {
"context": {
"merchant_id": "b64aa6bd-379c-4155-828e-ce7a3fa59f5b",
"campaign_id": "a69453b6-77ef-446d-808d-fe7f9738f01f",
"product_id": "0b74233e-80ef-4dfc-9b2b-3f4d8bd87eda",
"customer_id": "cust_sess_9a87d12f"
}
}
r = requests.post("https://api.pricient.co/request_price/", json=payload, headers=headers)
data = r.json()
print("Returned Price:", data["final_price"])
print("Tracking Request ID:", data["request_id"])
const axios = require('axios');
async function getPrice(token, context) {
const response = await axios.post('https://api.pricient.co/request_price/',
{ context },
{ headers: { Authorization: `Bearer ${token}` } }
);
return response.data;
}
Response (200 OK)
{
"request_id": "681a0ed6-01c5-4b53-a84a-dbc879ef06f0",
"final_price": 129,
"original_price": 129
}
3. Request Prices (Bulk / Multi-Product)
Retrieve optimized dynamic prices for multiple catalog products in a single high-performance roundtrip. Ideal for category pages, cart pages, or grid storefronts.
Request Body Schema
| Field | Type | Description |
|---|---|---|
| context.merchant_id Required | UUID | Merchant UUID identifier. |
| context.campaign_id Required | UUID | Campaign UUID identifier. |
| context.products Required | array<object> | List of product items to price: [{"product_id": "UUID"}, ...] |
| context.customer_id Optional | string | Unique customer/visitor ID. If omitted, Pricient auto-resolves via cookie/anonymous UUID. |
| context.customer_ip Optional | string | Explicit client IP override for server proxies (or pass via X-Forwarded-For header). |
| context.customer_timezone Optional | string | Client IANA Timezone (e.g. America/New_York). Auto-resolved if omitted. |
| context.customer_device_channel Optional | string | Client platform channel (ios, android, web). Auto-detected from User-Agent if omitted. |
| context.customer_screen_resolution Optional | string | Customer screen dimensions (e.g. 1920x1080). Auto-captured by Web SDK. |
| context.customer_language Optional | string | Customer locale / browser language (e.g. en-US, es-ES). |
| context.customer_page_url Optional | string | Current storefront URL. Auto-captured by Web SDK. |
| context.customer_referrer Optional | string | Referring URL / traffic source (e.g. https://google.com). |
| context.customer_user_agent Optional | string | Explicit User-Agent override for server proxies (or pass via User-Agent header). |
Code Examples
curl -X POST "https://api.pricient.co/multi_request_price/" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"context": {
"merchant_id": "b64aa6bd-379c-4155-828e-ce7a3fa59f5b",
"campaign_id": "a69453b6-77ef-446d-808d-fe7f9738f01f",
"customer_id": "cust_sess_9a87d12f",
"products": [
{"product_id": "0b74233e-80ef-4dfc-9b2b-3f4d8bd87eda"},
{"product_id": "681a0ed6-01c5-4b53-a84a-dbc879ef06f0"}
]
}
}'
const res = await fetch('https://api.pricient.co/multi_request_price/', {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
context: {
merchant_id: "b64aa6bd-379c-4155-828e-ce7a3fa59f5b",
campaign_id: "a69453b6-77ef-446d-808d-fe7f9738f01f",
customer_id: "cust_sess_9a87d12f",
products: [
{ product_id: "0b74233e-80ef-4dfc-9b2b-3f4d8bd87eda" },
{ product_id: "681a0ed6-01c5-4b53-a84a-dbc879ef06f0" }
]
}
})
});
const { results } = await res.json();
results.forEach(item => {
console.log(`Product ${item.product_identifier} -> Price: $${item.final_price}`);
});
import requests
payload = {
"context": {
"merchant_id": "b64aa6bd-379c-4155-828e-ce7a3fa59f5b",
"campaign_id": "a69453b6-77ef-446d-808d-fe7f9738f01f",
"customer_id": "cust_sess_9a87d12f",
"products": [
{"product_id": "0b74233e-80ef-4dfc-9b2b-3f4d8bd87eda"},
{"product_id": "681a0ed6-01c5-4b53-a84a-dbc879ef06f0"}
]
}
}
r = requests.post("https://api.pricient.co/multi_request_price/", json=payload, headers={"Authorization": f"Bearer {access_token}"})
print(r.json())
Response (200 OK)
{
"results": [
{
"product_identifier": "0b74233e-80ef-4dfc-9b2b-3f4d8bd87eda",
"final_price": 129,
"request_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"
},
{
"product_identifier": "681a0ed6-01c5-4b53-a84a-dbc879ef06f0",
"final_price": 199,
"request_id": "f6e5d4c3-b2a1-0f9e-8d7c-6b5a4f3e2d1c"
}
]
}
4. Log Purchase (Conversion Feedback)
Informs the reinforcement learning engine that a pricing request resulted in a purchase. This updates the model to continuously optimize future price recommendations.
Request Body Schema
| Field | Type | Description |
|---|---|---|
| request_id Required | UUID | The tracking request_id obtained from a previous /request_price/ call. |
| purchased Required | boolean | Must be true to record a completed conversion. |
Code Example
curl -X POST "https://api.pricient.co/make_purchase/" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"request_id": "681a0ed6-01c5-4b53-a84a-dbc879ef06f0",
"purchased": true
}'
const res = await fetch('https://api.pricient.co/make_purchase/', {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
request_id: storedRequestId,
purchased: true
})
});
const data = await res.json();
console.log('Purchase logged:', data.message);
import requests
payload = {
"request_id": "681a0ed6-01c5-4b53-a84a-dbc879ef06f0",
"purchased": True
}
r = requests.post("https://api.pricient.co/make_purchase/", json=payload, headers={"Authorization": f"Bearer {access_token}"})
print(r.json())
Response (200 OK)
{
"status": "success",
"message": "Purchase logged successfully."
}
5. Log Purchases (Bulk / Cart Conversion)
Logs conversions for multiple cart items simultaneously when a customer finishes checkout.
Code Example
curl -X POST "https://api.pricient.co/multi_make_purchase/" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"campaign_id": "a69453b6-77ef-446d-808d-fe7f9738f01f",
"items": [
{
"request_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"purchased": true,
"quantity": 1
},
{
"request_id": "f6e5d4c3-b2a1-0f9e-8d7c-6b5a4f3e2d1c",
"purchased": true,
"quantity": 2
}
]
}'
Response (200 OK)
{
"status": "success",
"message": "Purchases recorded successfully."
}
6. Inventory Synchronization
Keep Pricient's scarcity and inventory elasticity models up to date by synchronizing stock levels from your ERP or warehouse management system.
Code Example
{
"merchant_id": "b64aa6bd-379c-4155-828e-ce7a3fa59f5b",
"inventory_data": [
{
"product_id": "0b74233e-80ef-4dfc-9b2b-3f4d8bd87eda",
"inventory": 42
},
{
"product_name": "Premium Leather Jacket",
"inventory": 5
}
]
}
Response (200 OK)
{
"status": "success",
"updated_count": 2
}
7. Product Performance Statistics
Query real-time pricing statistics, evaluated price points, conversions, and expected revenue values for any active product.
Response (200 OK)
{
"product_id": "0b74233e-80ef-4dfc-9b2b-3f4d8bd87eda",
"product_name": "Enterprise Subscription",
"current_price": 199.00,
"min_price": 149.00,
"max_price": 249.00,
"total_requests": 1420,
"total_purchases": 284,
"conversion_rate": 0.20
}
Interactive API Tester
Test the pricing endpoint right from your browser. Input your Merchant API Key to fetch a real token, or test with demo credentials.
Credits & API Usage Quotas
Pricient uses a Credit Wallet model where credits represent price recommendation quotas. Only price calculation requests deduct credits from your balance. Conversion reporting, authentication, inventory updates, and statistics endpoints are completely free.
Credit Consumption by Endpoint
| Endpoint | Operation | Credit Cost |
|---|---|---|
POST /request_price/ |
Single product elastic price evaluation | 1 credit |
POST /multi_request_price/ |
Bulk catalog / cart pricing ($N$ products) | 1 credit per product |
POST /get_public_token/ |
Merchant API Key → JWT exchange | 0 credits (Free) |
POST /make_purchase/ |
Single checkout conversion logging | 0 credits (Free) |
POST /multi_make_purchase/ |
Multi-item cart conversion logging | 0 credits (Free) |
POST /update_inventory/ |
Catalog stock & inventory sync | 0 credits (Free) |
GET /product-stats/{id}/ |
Real-time performance & conversion stats | 0 credits (Free) |
- New Signups: All new merchants automatically receive 300 free starting credits upon account creation.
- Subscription Refills: Active subscriptions (Starter: 300 credits/month, Growth: 500+ credits/month) automatically refresh every billing cycle.
- Exhaustion Handling: If your credit balance drops below 1, pricing endpoints return
400 Bad Requestwith{"error": "Insufficient credits."}. Top up your wallet in your Merchant Settings.
Error Codes & Troubleshooting
Pricient returns standard HTTP status codes along with descriptive JSON error messages.
| Status Code | Meaning | Typical Reason & Solution |
|---|---|---|
| 200 OK | Success | The request succeeded and returned elastic pricing or recorded conversion. |
| 400 Bad Request | Validation Error | Missing required field (e.g. customer_id is required) or insufficient merchant credits. |
| 401 Unauthorized | Auth Failure | Expired or invalid JWT Bearer token or invalid merchant API Key. Exchange a new token via /get_public_token/. |
| 404 Not Found | Resource Missing | Campaign or product identifier not found for the merchant. |
| 405 Method Not Allowed | Invalid Method | Attempted GET on a POST-only route. |