Getting started for Sellers
This guide walks you through implementing the Agentic Commerce Protocol (ACP) as a seller so agents can create, update, and complete checkouts with your store.
Overview
As a seller, you implement a set of REST endpoints that agents call to conduct checkouts. You remain the merchant of record—calculating prices, managing inventory, and processing payments through your existing systems.
You are responsible for:
- Calculating all amounts (item prices, discounts, taxes, shipping)
- Managing inventory and availability
- Processing payments through your payment provider
- Fulfilling orders
Endpoints
ACP defines five REST endpoints. All use HTTPS, accept JSON, and return the complete checkout state.
| Endpoint | Description |
|---|---|
POST /checkout_sessions | Create a new checkout session |
GET /checkout_sessions/{id} | Retrieve checkout state |
POST /checkout_sessions/{id} | Update a checkout session |
POST /checkout_sessions/{id}/complete | Complete with payment |
POST /checkout_sessions/{id}/cancel | Cancel the session |
Create a checkout session
When an agent creates a checkout, calculate line item totals, available fulfillment options, and taxes based on the provided items and address.
POST /checkout_sessions
{
"items": [
{ "id": "sku_123", "quantity": 1 },
{ "id": "sku_456", "quantity": 2 }
],
"buyer": {
"first_name": "Ada",
"last_name": "Lovelace",
"email": "ada@example.com"
},
"fulfillment_address": {
"name": "Ada Lovelace",
"line_one": "123 Main St",
"city": "San Francisco",
"state": "CA",
"country": "US",
"postal_code": "94107"
}
}
>>>
{
"id": "chk_abc123",
"status": "not_ready_for_payment",
"currency": "usd",
"line_items": [
{
"id": "li_1",
"item": { "id": "sku_123", "quantity": 1 },
"base_amount": 3000,
"subtotal": 3000,
"tax": 270,
"total": 3270,
"description": "Wireless Headphones"
}
],
"fulfillment_options": [
{
"type": "shipping",
"id": "ship_std",
"title": "Standard Shipping",
"description": "5-7 business days",
"total": 545
},
{
"type": "shipping",
"id": "ship_exp",
"title": "Express Shipping",
"description": "1-2 business days",
"total": 1635
}
],
"totals": [
{ "type": "subtotal", "display_text": "Subtotal", "amount": 6000 },
{ "type": "tax", "display_text": "Estimated Tax", "amount": 540 },
{ "type": "total", "display_text": "Total", "amount": 6540 }
],
"messages": [
{ "type": "info", "message": "Please select a shipping method" }
]
}
Key points:
- The seller returns the complete checkout state
- Use
messagesto communicate next steps to the agent
Update a checkout session
Agents update sessions to change items, select fulfillment options, or modify addresses. Recalculate totals after each update.
POST /checkout_sessions/chk_abc123
{
"fulfillment_option_id": "ship_std"
}
>>>
{
"id": "chk_abc123",
"status": "ready_for_payment",
"currency": "usd",
"line_items": [...],
"selected_fulfillment_option": {
"type": "shipping",
"id": "ship_std",
"title": "Standard Shipping",
"total": 545
},
"totals": [
{ "type": "subtotal", "display_text": "Subtotal", "amount": 6000 },
{ "type": "shipping", "display_text": "Shipping", "amount": 500 },
{ "type": "tax", "display_text": "Tax", "amount": 585 },
{ "type": "total", "display_text": "Total", "amount": 7085 }
]
}
When a fulfillment option is selected and all required information is present, transition the status to ready_for_payment.
Complete a checkout session
The agent sends a payment token to complete the checkout. The payment_data contains an ACP-compatible token from the Payment Service Provider (PSP) representing the buyer's payment method.
POST /checkout_sessions/chk_abc123/complete
{
"payment_data": {
"provider": "psp",
"token": "token_abc123def456ghi789"
}
}
>>>
{
"id": "chk_abc123",
"status": "completed",
"order": {
"id": "ord_xyz789",
"url": "https://example.com/orders/ord_xyz789"
},
"messages": [
{ "type": "success", "message": "Order placed successfully" }
]
}
When you receive the complete request:
- Create a payment using the supplied token and your PSP.
- Create an order in your system
- Return the order details
Cancel a checkout session
Canceling a session releases any reserved inventory and prevents further updates.
POST /checkout_sessions/chk_abc123/cancel
{}
>>>
{
"id": "chk_abc123",
"status": "canceled",
"messages": [
{ "type": "info", "message": "Checkout canceled" }
]
}