callbotagent.aiDocs
v1 · Contract draft
ENPL
Open dashboard
Preview

Create order / repurchase intent

Preview documentation / simulated contract (draft). Schemas and examples reflect the planned Commerce API v1 — final values will be confirmed when the production contract is frozen.

POST /orders

Description

Create/upsert order (standard) or repurchase intent — full order, not a lead. Base URL: https://api.callbotagent.ai/api/v1/commerce.

Required scope

orders:write

Headers

Header Value Required
Content-Type application/json (gdy body) when body present
X-CBA-Key-Id key identifier (in examples: cba_test_••••••••) yes
X-CBA-Timestamp RFC 3339 UTC yes
X-CBA-Nonce unique nonce within the 300 s window yes
X-CBA-Content-SHA256 SHA-256 hex surowego body (e3b0c44… dla pustego) yes
X-CBA-Signature hmac-sha256=<hex> yes
Idempotency-Key idempotency key mutations: yes

Body parameters

Field Type Required Description
order_kind enum yes standard
external_order_id string yes Stable partner order ID
external_customer_id string yes Customer reference
items[] array yes Line items: variant, quantity, price, currency
contact_permission object yes status + consent proof (especially repurchase)
source_version string yes Monotonic source version
contact_not_before datetime no Earliest contact time (RFC 3339)
priority integer no Queue priority
confidence string no Decimal string 0–1

Example request

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: n_8f3a2c1b" \
  -H "X-CBA-Content-SHA256: <sha256-body>" \
  -H "X-CBA-Signature: hmac-sha256=<hex>" \
  -H "Idempotency-Key: idem-orders-post" \
  -H "Content-Type: application/json" \
  -d '{"external_order_id":"RB-5510","order_kind":"repurchase_intent","external_customer_id":"CUSTOMER-8821","source_version":"2026-07-11T09:00:00Z","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":{"status":"granted","basis":"prior_purchase","reference":"order-4821"}}'

Example response

{
  "external_order_id": "RB-5510",
  "order_kind": "repurchase_intent",
  "processing_state": "received",
  "correlation_id": "corr_7c2f4d10"
}

Possible errors

Status code Meaning
401 invalid_signature / expired_timestamp / replay_nonce HMAC / replay window
403 insufficient_scope missing required scope
404 resource_not_found resource unavailable for principal
409 idempotency_key_reused / stale_source_version idempotency / version conflict
422 validation_failed body does not match schema / invariants
429 rate_limited limits — see Retry-After

Related