Pivota

Integration Guide

Everything you need to integrate with Pivota Agent API

Choose your language:

1. Installation

pip install pivota-agent

2. Quick Start

from pivota_agent import PivotaAgentClient
import requests

API_BASE = "https://web-production-fedb.up.railway.app/agent/v1"
API_KEY = "YOUR_API_KEY"

client = PivotaAgentClient(api_key=API_KEY, base_url=API_BASE)

# 1) Search products
search = client.search_products(query="laptop", merchant_id="merch_xxx", limit=5)
product_id = search["products"][0]["id"]

# 2) Resolve purchasable variant_id via cart/validate (recommended before checkout)
cart = requests.post(
    f"{API_BASE}/cart/validate?merchant_id=merch_xxx&shipping_country=US",
    headers={"X-API-Key": API_KEY},
    json=[{"product_id": product_id, "quantity": 1}],
    timeout=30,
)
cart.raise_for_status()
variant_id = cart.json()["items"][0]["variant_id"]

# 3) Hosted checkout: mint checkout_token + checkout_url (Checkout UI)
intent = requests.post(
    f"{API_BASE}/checkout/intents",
    headers={"X-API-Key": API_KEY},
    json={
        "items": [
            {
                "product_id": product_id,
                "variant_id": variant_id,
                "merchant_id": "merch_xxx",
                "quantity": 1,
            }
        ],
        "return_url": "https://developer.pivota.cc/return",
        "buyer_ref": "guest:YOUR_UUID",
    },
    timeout=30,
)
intent.raise_for_status()
print("Open hosted checkout URL:", intent.json()["checkout_url"])

3. Complete Example

from pivota_agent import PivotaAgentClient
import requests

API_BASE = "https://web-production-fedb.up.railway.app/agent/v1"
API_KEY = "YOUR_API_KEY"
MERCHANT_ID = "merch_xxx"

client = PivotaAgentClient(api_key=API_KEY, base_url=API_BASE)

# 1) Search products
search = client.search_products(query="coffee mug", merchant_id=MERCHANT_ID, limit=5)
product_id = search["products"][0]["id"]

# 2) Resolve purchasable variant_id (cart/validate)
cart = requests.post(
    f"{API_BASE}/cart/validate?merchant_id={MERCHANT_ID}&shipping_country=US",
    headers={"X-API-Key": API_KEY},
    json=[{"product_id": product_id, "quantity": 2}],
    timeout=30,
)
cart.raise_for_status()
variant_id = cart.json()["items"][0]["variant_id"]

# 3) Hosted checkout (Checkout UI) – recommended for agent apps with end users
intent = requests.post(
    f"{API_BASE}/checkout/intents",
    headers={"X-API-Key": API_KEY},
    json={
        "items": [
            {
                "product_id": product_id,
                "variant_id": variant_id,
                "merchant_id": MERCHANT_ID,
                "quantity": 2,
            }
        ],
        "return_url": "https://developer.pivota.cc/return",
        "buyer_ref": "guest:YOUR_UUID",
        "market": "US",
        "source": "your_agent_app",
    },
    timeout=30,
)
intent.raise_for_status()
print("Open hosted checkout URL:", intent.json()["checkout_url"])

# Optional: Checkout UI can fetch prefill via X-Checkout-Token
prefill = requests.get(
    f"{API_BASE}/checkout/prefill",
    headers={"X-Checkout-Token": intent.json()["checkout_token"]},
    timeout=30,
).json()
print("Prefill available:", prefill.get("prefill") is not None)