Custom store integration: end-to-end
Preview documentation. The interface is being rolled out — examples are indicative, and we will confirm final values at launch.
This guide takes you from an empty store to the first confirmed conversation
results — in five steps. Custom store integration relies entirely on the public
Commerce API: you send catalog, customers, and repurchase intents, and we
return dispositions and the final order state. Base URL for all calls:
https://api.callbotagent.ai/api/v1/commerce.
Before you begin
You need an API key (always masked in the dashboard and examples:
cba_test_••••••••) and scopes matching the operations you perform. Sign every
request (HMAC v1) — details in Authentication. Order
matters: catalog and customers first, then orders — the bot will not offer a
product or call a customer it cannot verify.
End-to-end flow
Sync the catalog
POST /products/batch — send the catalog with stable external IDs,
availability, currency, and categories. The bot will not offer a product it
cannot verify in your catalog, so a complete, current feed is the foundation of
the integration.
Add customers with consent
PUT /customers/{externalCustomerId} — pass phone in E.164, locale, and
consent proof for contact. Records without valid consent do not enter the calling
queue — that is mandatory, not optional.
Submit repurchase intents
POST /orders with order_kind=repurchase_intent, expected contact date in
contact_not_before, explicit line items and prices. Intents appear in the
dashboard as orders — never as anonymous sales contacts.
Owner policy takes precedence
Countries, calling hours and days, retry policy, DNC lists, and store-owner budget always win. Partner data may narrow policy (e.g. a tighter contact window) but never relax it.
Receive results
Consume signed webhooks or poll GET /orders/{externalOrderId}/result. In
final_order_snapshot you get the final conversation state: confirmed,
modified, or declined products and prices.
Field mapping
Common mappings from your platform model to Commerce API fields.
| Your platform | Commerce API |
|---|---|
| Merchant / market | One store + custom connector |
| Repurchase prediction | order_kind=repurchase_intent |
| Expected contact date | contact_not_before |
| Prediction confidence / score | priority / confidence |
| Final decision after conversation | final_order_snapshot |
If your platform distinguishes multiple markets or sales accounts, all map to one store served by the custom connector — keep segmentation in external IDs and metadata, not separate integrations.
Partner profiles on the custom platform
Partners predicting repurchases use the same Commerce API as any other custom store. There is no separate endpoint or platform for them — only how they map their data to contract fields differs.
Typical mapping for foresight / repurchase:
- repurchase prediction →
order_kind=repurchase_intent, - expected next purchase date →
contact_not_before, - prediction confidence →
priority/confidence.
Catalog, customers with consent, owner policy precedence, and result delivery work identically to any other custom store. The partner profile is only a mapping layer — the rest of the flow is unchanged.