Preview documentation. The interface is being rolled out — examples are indicative, and we will confirm final values at launch.
Orders and repurchase intents
The Orders resource handles two object kinds, distinguished by order_kind:
standard— canonical store order (confirmation, upsell, verification).repurchase_intent— repurchase intent: a complete order "in intent" (line items, prices, quantities) to confirm in a customer conversation.
A repurchase intent is a full order, not a lead to process — it goes through
the same qualification, scheduling, and result model as a standard order.
Base URL: https://api.callbotagent.ai/api/v1/commerce. Sign requests with HMAC
(X-CBA-Key-Id, X-CBA-Timestamp, X-CBA-Signature); mutations add
Idempotency-Key.
Repurchase intent fields
| Field | Type | Description |
|---|---|---|
order_kind |
enum | standard | repurchase_intent. |
contact_not_before |
string | Expected contact date (RFC 3339 UTC). |
priority |
integer | Queue priority (higher = more urgent). |
confidence |
string | Prediction confidence as decimal string 0–1, e.g. "0.82". |
items[] |
array | Line items: external_variant_id, quantity, price, currency. |
contact_permission |
object | Contact basis: basis, reference. |
Operations
POST /orders
Creates or upserts an order or repurchase intent (per order_kind). Scope
orders:write. Response includes processing_state (initial: received).
curl -X POST https://api.callbotagent.ai/api/v1/commerce/orders \
-H "X-CBA-Key-Id: cba_test_••••••••" \
-H "X-CBA-Timestamp: 2026-07-10T12:34:56Z" \
-H "X-CBA-Signature: v1=9f8c2a...e41" \
-H "Idempotency-Key: order-RB-5510-01" \
-H "Content-Type: application/json" \
-d '{
"external_order_id": "RB-5510", "order_kind": "repurchase_intent",
"external_customer_id": "CUSTOMER-8821",
"contact_not_before": "2026-07-14T08:00:00Z", "priority": 5, "confidence": "0.82",
"items": [{ "external_variant_id": "SKU-ROUTER-01-BLK", "quantity": 1, "price": "349.00", "currency": "PLN" }],
"contact_permission": { "basis": "prior_purchase", "reference": "order-4821" }
}'
# 201 Created → { "external_order_id": "RB-5510", "processing_state": "received" }const body = {
external_order_id: "RB-5510", order_kind: "repurchase_intent",
external_customer_id: "CUSTOMER-8821",
contact_not_before: "2026-07-14T08:00:00Z", priority: 5, confidence: "0.82",
items: [{ external_variant_id: "SKU-ROUTER-01-BLK", quantity: 1, price: "349.00", currency: "PLN" }],
contact_permission: { basis: "prior_purchase", reference: "order-4821" },
};
const res = await fetch("https://api.callbotagent.ai/api/v1/commerce/orders", {
method: "POST", headers: {
"X-CBA-Key-Id": "cba_test_••••••••",
"X-CBA-Timestamp": "2026-07-10T12:34:56Z",
"X-CBA-Signature": "v1=9f8c2a...e41",
"Idempotency-Key": "order-RB-5510-01",
"Content-Type": "application/json",
}, body: JSON.stringify(body),
});
const data = await res.json(); // { external_order_id: "RB-5510", processing_state: "received" }$body = [
"external_order_id" => "RB-5510", "order_kind" => "repurchase_intent",
"external_customer_id" => "CUSTOMER-8821",
"contact_not_before" => "2026-07-14T08:00:00Z", "priority" => 5, "confidence" => "0.82",
"items" => [["external_variant_id" => "SKU-ROUTER-01-BLK", "quantity" => 1, "price" => "349.00", "currency" => "PLN"]],
"contact_permission" => ["basis" => "prior_purchase", "reference" => "order-4821"],
];
$ch = curl_init("https://api.callbotagent.ai/api/v1/commerce/orders");
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"X-CBA-Key-Id: cba_test_••••••••",
"X-CBA-Timestamp: 2026-07-10T12:34:56Z",
"X-CBA-Signature: v1=9f8c2a...e41",
"Idempotency-Key: order-RB-5510-01",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode($body),
]);
$data = json_decode(curl_exec($ch), true); // { external_order_id: "RB-5510", ... }GET /orders/{externalOrderId}
Returns the canonical order with current processing_state. Scope orders:read.
PATCH /orders/{externalOrderId}
Versioned update (optimistic concurrency via source version); changing line
items/amounts triggers re-qualification. Stale version →
409 stale_source_version.
POST /orders/{externalOrderId}/cancel
Race-safe cancellation (CAS-safe): for completed/cancelled returns state
unchanged.
GET /orders/{externalOrderId}/result
GET /orders/{externalOrderId}/calls
Result (final_order_snapshot) and contact attempts — full detail in
./results.md; change notifications in ./webhooks.md.