Preview documentation. The interface is being rolled out — examples are indicative, and we will confirm final values at launch.
Qualification and scheduling
Qualification and scheduling are not a partner endpoint set — they are platform-side policy every accepted order and repurchase intent passes through. The partner supplies data and narrows the offer but cannot relax account-owner policy.
Base URL: https://api.callbotagent.ai/api/v1/commerce. Sign requests with HMAC
(X-CBA-Key-Id, X-CBA-Timestamp, X-CBA-Signature).
Path of an accepted order
After POST /orders the record passes successive gates. Each may reject it
(processing_state: rejected with a reason) or allow it to continue:
| Stage | Check |
|---|---|
| Consent | consent.status: granted and valid customer consent proof. |
| DNC | Number not on Do-Not-Call list and not withdrawn. |
| Filters | Owner filters (tags, product/category exclusions, sales rules). |
| Availability | Product and variant active and available (inventory > 0). |
| Budget | Account has contact budget/capacity available. |
After successful qualification the record enters scheduling: hour/day
windows, customer time zone, quiet hours, and contact_not_before (for intents
— expected date). The system will not call earlier than the most restrictive of
these constraints.
Policy hierarchy
When settings overlap, the most restrictive wins. Precedence order:
| Priority | Layer | Can |
|---|---|---|
| 1 (highest) | DNC and compliance | block contact unconditionally |
| 2 | Account owner | set windows, budget, filters, quiet hours |
| 3 (lowest) | Partner (API) | only narrow offer and target within 1–2 |
The partner never expands policy. Settings sent through the API may only narrow what the account owner and compliance (DNC, consent) allow.
Effective configuration preview
GET /configuration/effective
Read-only. Returns effective configuration, readiness (readiness), and
blockers — no secrets. Scope configuration:read. Use to diagnose "why is this
record not calling".
curl https://api.callbotagent.ai/api/v1/commerce/configuration/effective \
-H "X-CBA-Key-Id: cba_test_••••••••" \
-H "X-CBA-Timestamp: 2026-07-10T12:34:56Z" \
-H "X-CBA-Signature: v1=9f8c2a...e41"
# 200 OK → {
# "readiness": "blocked",
# "calling_windows": { "timezone": "Europe/Warsaw", "days": ["mon","tue","wed","thu","fri"],
# "hours": "09:00-17:00" },
# "blockers": [{ "code": "no_budget", "message": "No contact budget available" }]
# }const res = await fetch(
"https://api.callbotagent.ai/api/v1/commerce/configuration/effective",
{ headers: {
"X-CBA-Key-Id": "cba_test_••••••••",
"X-CBA-Timestamp": "2026-07-10T12:34:56Z",
"X-CBA-Signature": "v1=9f8c2a...e41",
} },
);
const cfg = await res.json();
// { readiness: "blocked", calling_windows: {...}, blockers: [{ code: "no_budget", ... }] }$ch = curl_init("https://api.callbotagent.ai/api/v1/commerce/configuration/effective");
curl_setopt_array($ch, [
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",
],
]);
$cfg = json_decode(curl_exec($ch), true);
// { readiness: "blocked", calling_windows: {...}, blockers: [...] }Read processing_state for a single record via
GET /orders/{externalOrderId} (./orders.md); full result and
attempt model in ./results.md.