# ACP Overview

Introduction to the Agentic Commerce Protocol for selling AVCodex agent services.

---

The Agentic Commerce Protocol (ACP) lets AI agents discover and purchase products and services from your AVCodex agent. Instead of requiring a human to browse a website, an external agent can programmatically find what you offer, create a checkout session, and complete a purchase. All through a REST API.

For an AV business, that opens new sales surfaces. A buyer's agent could discover and purchase your room-tuning service, your control-system audit, or your SOP library directly. ACP is an open protocol, so we keep the protocol name as is.

## How it works

ACP follows a four-step flow:

```
1. Discovery     Agent fetches your product catalog
                 GET /acp/{appId}/products

2. Checkout      Agent creates a checkout session with selected items
                 POST /acp/{appId}/checkout_sessions

3. Payment       Agent completes the checkout, triggering payment
                 POST /acp/{appId}/checkout_sessions/{id}/complete

4. Fulfillment   Order is created, fulfilled, and webhook fires
                 Your webhook endpoint receives order details
```

## Two access modes

ACP supports two ways for purchases to happen:

**External API (agent-to-agent).** An external AI agent (ChatGPT, Perplexity, a custom buyer's agent) discovers your product catalog via the REST API, creates a checkout session, completes it, and receives the result via webhook.

**In-chat checkout.** A consumer chats with your AVCodex agent. When the agent invokes a priced tool (a room audit, a programming hour, a remote-commissioning session), the system shows an inline Stripe checkout card. The consumer pays, the tool runs, and the result is delivered in the conversation.

Both modes use the same underlying infrastructure. This documentation covers the external API mode.

## Getting started

### 1. Publish products

In your agent's builder, go to **Publish > Catalog** and create products. Each product has a name, description, price, and fulfillment type (automatic or manual). Examples for AV:

- "Q-SYS Reflect onboarding hour."
- "Remote commissioning session, single room."
- "RFP response review, 24-hour turnaround."

### 2. Create an ACP API key

In the same Catalog section, create an API key. You'll see the raw key once. Copy it and store it securely. The key has the prefix `acp_`.

### 3. Discover and purchase

Use the key to authenticate checkout operations. Product discovery endpoints are public and need no authentication.

## Base URL

All ACP endpoints are scoped to a specific agent:

```
https://app.avcodex.com/acp/{appId}
```

Replace `{appId}` with your agent's UUID.

## Endpoint summary

### Public (no authentication)

| Method | Path                                  | Description                  |
|--------|---------------------------------------|------------------------------|
| `GET`  | `/acp/{appId}/.well-known/agent.json` | Agent discovery card.        |
| `GET`  | `/acp/{appId}/products`               | List active products.        |

### Authenticated (Bearer token)

| Method | Path                                              | Description                       |
|--------|---------------------------------------------------|-----------------------------------|
| `POST` | `/acp/{appId}/checkout_sessions`                  | Create checkout session.          |
| `GET`  | `/acp/{appId}/checkout_sessions/{id}`             | Get checkout session status.      |
| `POST` | `/acp/{appId}/checkout_sessions/{id}`             | Update checkout session.          |
| `POST` | `/acp/{appId}/checkout_sessions/{id}/complete`    | Complete checkout.                |
| `POST` | `/acp/{appId}/checkout_sessions/{id}/cancel`      | Cancel checkout.                  |

## What's next

- [Authentication](/docs/acp/authentication) - how to authenticate API requests.
- [Agent Discovery](/docs/acp/agent-discovery) - product discovery endpoints.
- [Checkout](/docs/acp/checkout) - creating and completing purchases.
- [Webhooks](/docs/acp/webhooks) - receiving order notifications.

*AVCodex · Your AV expertise. Amplified by AI.*