Documentation API & Integrations API reference (index) Preview
API reference (index)
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.
Complete list of public Commerce API v1 operations. Base URL:
https://api.callbotagent.ai/api/v1/commerce. Method pages are synchronized with
the OpenAPI file (version 2026.07.11-draft.1).
Conceptual resources
Discovery
Method and path
Description
Scope
Page
GET /capabilitiesContract version, limits, supported order kinds, events, and feature flags.
commerce:readCapabilities
GET /configuration/effectiveSanitized effective config, readiness, and blockers (no owner secrets).
configuration:readEffective configuration
Catalog
Method and path
Description
Scope
Page
POST /products/batchIdempotent upsert of up to 500 products with variants/categories.
catalog:writeCatalog upsert (batch)
GET /productsCursor list / search / filter.
catalog:readList products
GET /products/{externalProductId}Product detail with variants.
catalog:readProduct details
DELETE /products/{externalProductId}Tombstone/archive — never hard delete. May trigger requalification of active orders.
catalog:writeArchive product
Customers
Method and path
Description
Scope
Page
PUT /customers/{externalCustomerId}Profile, BCP 47 locale, and consent proof.
customers:writeUpsert customer
GET /customers/{externalCustomerId}Sanitized detail (no unnecessary PII).
customers:readCustomer details
POST /customers/{externalCustomerId}/anonymizeIdempotent erasure / anonymization workflow (GDPR).
customers:eraseAnonymize customer
Orders
Method and path
Description
Scope
Page
POST /ordersCreate/upsert order (standard) or repurchase intent — full order, not a lead.
orders:writeCreate order / repurchase intent
GET /orders/{externalOrderId}Canonical order + processing_state.
orders:readOrder details
PATCH /orders/{externalOrderId}Versioned update; after qualification may trigger requalification (CAS).
orders:writeUpdate order
POST /orders/{externalOrderId}/cancelCAS-safe cancellation.
orders:writeCancel order
Results
Method and path
Description
Scope
Page
GET /orders/{externalOrderId}/resultFinal result projection: processing_state, disposition, business_outcome, snapshot.
results:readOrder result
GET /orders/{externalOrderId}/callsCursor list of attempts + reports/transcript policy.
results:readCall attempt history
Rules
Method and path
Description
Scope
Page
PUT /sales-rules/{externalRuleId}replacement/upsell/cross-sell/quantity/price constraint.
rules:writeUpsert sales rule
GET /sales-rulesCursor list of sales rules.
rules:readList sales rules
GET /sales-rules/{externalRuleId}Rule detail.
rules:readSales rule details
DELETE /sales-rules/{externalRuleId}Archive rule (not hard delete).
rules:writeArchive sales rule
Webhooks
Method and path
Description
Scope
Page
GET /webhook-subscriptionURL masked, events, health — no secret.
webhooks:readRead webhook subscription
PUT /webhook-subscriptionHTTPS URL, event allowlist, active flag.
webhooks:writeUpsert webhook subscription
POST /webhook-subscription/secret/rotateReveal-once secret + overlap rotation window.
webhooks:writeRotate webhook secret
POST /webhook-subscription/testSame outbox/delivery path, test=true flag.
webhooks:writeTest webhook delivery
GET /webhook-deliveriesCursor log with masked/sanitized request/response.
webhooks:readWebhook delivery log
POST /webhook-deliveries/{deliveryId}/replayNew attempt for the same immutable event.
webhooks:writeReplay webhook delivery
Conventions
JSON snake_case; money = decimal string + ISO 4217; phone E.164; locale BCP 47.
Lists: opaque cursor, limit default 50 / max 200.
Mutations: Idempotency-Key + optional source_version (409 on stale).
Errors: application/problem+json — Errors .
Auth: HMAC .
