How to Use ChatBasket

A practical guide for merchants setting up and operating ChatBasket as your hosted ACP/UCP endpoint and control plane for AI agent order intents.

Initial Setup Flow

Follow these steps to get ChatBasket ready to host your merchant ACP/UCP endpoints and evaluate AI agent order intents before they reach checkout.

Create your merchant account

Create a policy

Define rules: substitution rules, out-of-stock handling, delivery windows, and review thresholds.

Activate the policy

Policies start as drafts. Activate to enforce rules on incoming intents.

Add the AI agent that will submit order intents. Give it a name and identifier.

Generate an API key

Create an API key for the agent to authenticate when submitting intents. The key is shown once - copy it immediately.

Share the API key with your agent developer

Send the API key securely to the team building the AI agent. They'll use it in the X-API-Key header when calling your merchant ACP or UCP endpoint hosted by ChatBasket.

Configure webhooks (optional)

Set up a webhook URL in Settings to push intent decision events to your OMS or backend system. ChatBasket will POST notifications when intents are submitted, reviewed, approved, rejected, or need clarification.

Ready to go: Once you have an active policy and an agent with an API key, the agent can start submitting order intents.

Section Guide

Here's what each section of the admin dashboard does and when to use it.

Dashboard

Your at-a-glance overview. Shows intents today, blocked/review decisions, active agents, and current policy.

Click any metric to jump to filtered views
Use "Create Demo Intent" to test your policy without a real agent

Agents

Manage AI agents that submit order intents to your merchant.

Create agent: Add a new agent with name, provider, and identifier
Generate API key: Create authentication credentials for the agent
Pause/Resume: Temporarily disable an agent without deleting it
View intents: See recent order intents submitted by each agent

Policies

Define and manage rules that control what order intents are allowed, blocked, or sent for review.

Create policy: Start with a draft, configure rules, then activate
Rules include: Max order value, max items, review threshold, allowed categories, blocked SKUs, rate limits, geo-fence
Activate: Only one policy can be active at a time per scope
Archive: Deactivate old policies while keeping history

Order Intents

View all order intents submitted to your merchant ACP/UCP endpoints (hosted by ChatBasket) and their policy decisions.

Filter by: Status, decision (allow/block/review/clarify), agent, date range
Review intents: Approve or reject intents that require human review
View details: See items, totals, delivery address, fulfillment mode, and audit timeline

Audit Logs

Complete history of all actions taken in the system.

Track policy changes, order decisions, agent modifications
Filter by action type, entity, or date
Use for compliance, debugging, and dispute resolution

Users

Manage team members who can access the admin dashboard.

Invite users: Send email invitations to colleagues
Roles: Admin (full access), Operator (manage agents/policies/orders), Read-only (view only)
Update roles: Change permissions as team needs evolve

Settings

Configure merchant-level settings like outbound webhooks.

Webhook URL: ChatBasket will POST order events to this endpoint (your OMS or backend)
Webhook secret: Used to sign payloads so you can verify authenticity

Ongoing Operations

Daily monitoring

Check the Dashboard regularly to monitor order volume and decision distribution. Look for:

Unusual spikes in blocked intents (may indicate agent issues or policy too strict)
High volume of review decisions (consider adjusting thresholds)
New agents appearing that you don't recognize

Reviewing order intents

When an order intent triggers the review decision, a human must approve or reject it before it can proceed.

Don't ignore review queue: Intents pending review will not proceed to your checkout until approved. Check this regularly or set up webhook alerts.

To review an intent:

Go to Order Intents and filter by Decision: Review
Click an intent to see full details: items, totals, policy reasons
Click Approve Intent to allow it to proceed, or Reject Intent to block it
Your decision is logged in the audit trail with timestamp

Handling clarification requests

When an order intent has decision clarify, the agent needs to provide more information (e.g., delivery ZIP code, age verification, store ID for pickup).

The API response tells the agent exactly what fields are missing
The agent should resubmit with the required information
No manual action needed from you unless issues persist

Updating policies

As your business needs change, update your policy rules:

Go to Policies and click your active policy
Adjust rules (limits, categories, rate limits, etc.)
Click Save rules - changes take effect immediately

Tip: For major policy changes, consider creating a new policy version. Create a new draft, configure it, then activate it (which archives the old one).

Managing agents

When onboarding a new AI agent partner:

Create the agent in Agents
Generate an API key and share it securely with the agent developer
Monitor their first few orders closely
Adjust policy if needed based on their order patterns

If an agent is misbehaving (too many blocked orders, suspicious patterns):

Pause the agent to temporarily stop accepting their intents
Revoke API key to force re-authentication
Delete the agent if relationship is terminated

Webhook Integration (Outbound)

When an order intent is approved (automatically or after human review), ChatBasket can POST the approved intent to your OMS or backend system. Your merchant systems then create the actual order. This ensures only validated intents reach your fulfillment systems.

Events ChatBasket will send

intent.submitted - Intent received and evaluated against policy.
intent.approved - Intent approved (auto or human) and eligible to be forwarded to OMS.
intent.rejected - Intent rejected (auto or human). Do not create or fulfill an order.

Verifying webhooks

Each webhook includes a signature for verification:

Headers:
  X-ChatBasket-Signature: [sha256 hash]
  X-ChatBasket-Timestamp: [unix timestamp]

Verification:
  expected = sha256(webhook_secret + timestamp + "." + body)
  compare expected == X-ChatBasket-Signature

API Reference

For agent developers integrating with your merchant ACP endpoint hosted by ChatBasket:

Submit intent (ACP/UCP)

Merchant ACP endpoint (hosted by ChatBasket):
POST https://your-chatbasket-instance.com/api/v1/intent
X-API-Key: cb_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Or UCP endpoint (hosted by ChatBasket):
POST https://your-chatbasket-instance.com/.well-known/ucp
X-API-Key: cb_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "externalIntentId": "order-123",
  "items": [
    {"sku": "SKU-123", "name": "Product", "quantity": 2, "unitPrice": 9.99, "category": "grocery"}
  ],
  "customer": {"id": "cust_456", "email": "customer@example.com"},
  "shippingAddress": {"zip": "94105"}
}

Response statuses

approved - Intent accepted, proceed to checkout
pending_review - Waiting for human approval
needs_clarification - Missing required fields
rejected - Blocked by policy