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.

EndpointDescription
POST /checkout_sessionsCreate a new checkout session
GET /checkout_sessions/{id}Retrieve checkout state
POST /checkout_sessions/{id}Update a checkout session
POST /checkout_sessions/{id}/completeComplete with payment
POST /checkout_sessions/{id}/cancelCancel 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 messages to 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:

  1. Create a payment using the supplied token and your PSP.
  2. Create an order in your system
  3. 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" }
  ]
}

Next steps

Checkout lifecycle

Learn how checkout sessions transition between states and what each status means.

Learn more
Checkout API reference

See the complete schema definitions for all request and response objects.

Learn more
Documentation | Agentic Commerce Protocol