Preview

Preview documentation. The interface is being rolled out — examples are indicative, and we will confirm final values at launch.

Quick start

This guide walks you from creating a key to receiving your first conversation result in four steps. Send all calls to the base URL https://api.callbotagent.ai/api/v1/commerce, and sign every request with HMAC. In examples, the key ID is always masked: cba_test_••••••••.

Before you begin

An active account and configured store.
An API key with secret (create it in the dashboard — you see the secret only once).
A server-side environment where you can store the secret securely.

Four steps

Create an API key

In the dashboard (API Console → Keys), generate a pair: public key_id and secret. You see the secret only once (reveal-once) — save it immediately. Grant only the scopes you need — for this scenario, orders:write and results:read are enough. UI flow: Key generation; signing algorithm: Authentication.

Sign the request

Build the canonical string from method, path, query, timestamp, nonce, and body hash, then compute the HMAC-SHA256 signature. Include headers X-CBA-Key-Id, X-CBA-Timestamp, X-CBA-Nonce, X-CBA-Content-SHA256, and X-CBA-Signature. The timestamp must fall within a 300-second window. The full algorithm is in Authentication.

Send an order or repurchase intent

Call POST /orders to pass a commerce event that qualifies the contact for a conversation. For mutations, include the Idempotency-Key header to retry safely — see Idempotency. Example below.

Receive the result

You get the conversation result in two ways: via webhook (push, recommended) or by polling the results resource (using the results:read scope). Webhooks are faster and do not consume read rate limits.

Example: create an order

POST /orders

curl -X POST "https://api.callbotagent.ai/api/v1/commerce/orders" \
  -H "X-CBA-Key-Id: cba_test_••••••••" \
  -H "X-CBA-Timestamp: 2026-07-11T10:00:00Z" \
  -H "X-CBA-Nonce: 6a1f9c2e-7b40-4d2a-9c11-2e5f8a0d1b33" \
  -H "X-CBA-Content-SHA256: 8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4" \
  -H "X-CBA-Signature: hmac-sha256=…" \
  -H "Idempotency-Key: 9f4e6c1a-2d5b-4c8e-9a7f-1b2c3d4e5f60" \
  -H "Content-Type: application/json" \
  -d '{
        "external_id": "ORD-2026-0001",
        "currency": "PLN",
        "total_amount": "129.00",
        "locale": "pl-PL",
        "customer": { "phone": "+48512345678" },
        "line_items": [
          { "sku": "SKU-100", "quantity": 1, "unit_amount": "129.00" }
        ]
      }'

const res = await fetch(`${baseUrl}/api/v1/commerce/orders`, { method: 'POST', headers: signedHeaders(keyId, body), body: JSON.stringify(body) });

$response = $client->post('/api/v1/commerce/orders', ['headers' => signed_headers($keyId, $body), 'json' => $body]);

A 201 Created response includes the CallBotAgent-side order identifier. If you repeat the same Idempotency-Key with an identical body, you receive the same stored response, not a duplicate.

Next steps

Idempotency — how to retry writes safely.
Pagination and limits — payload sizes and rate limits.
Errors — how to read application/problem+json.
Custom store / API connector — full custom store integration setup.