Pricient REST API v2.0

Developer Integration & API Reference

Learn how to connect your storefront, e-commerce cart, or internal catalog with Pricient's real-time pricing engine in minutes.

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.

Security Architecture (Dual-Token Pattern)
Your private Merchant API Key should never be exposed to the user browser. Client-side applications (such as storefront Single Page Apps) exchange the Merchant API Key via a server-side proxy or public exchange endpoint for a short-lived JWT Access Token (with limited_access privileges restricted only to pricing and checkout conversion calls).

End-to-End Integration Flow

1

Authenticate

Exchange Merchant API Key for a scoped 1-hour JWT token.

2

Query Price

Call /request_price/ on product page load to get the dynamic recommended price.

3

Customer Buys

Display the final price and capture customer transaction session.

4

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

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

Zero Boilerplate Tracking
When you include 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

HTML Script Tag (CDN)
<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

Storefront JavaScript
// 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:

Proxy HTTP 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.

POST /get_public_token/ Public Endpoint

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)

Status: 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.

POST /request_price/ Bearer Auth

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)

Status: 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.

POST /multi_request_price/ Bearer Auth

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)

Status: 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.

POST /make_purchase/ Bearer Auth

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

POST /multi_make_purchase/ Bearer Auth

Code Example

cURL 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: 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.

POST /update_inventory/ Merchant Key

Code Example

Payload Format
{
  "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: 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.

GET /product-stats/{product_id}/ Session / Bearer

Response (200 OK)

Status: 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)
Wallet Rules & Refills
  • 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 Request with {"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.