API Reference – Agentic Commerce Protocol

API Reference

Complete ACP protocol API reference documentation based on OpenAPI 3.1 specification.

🔗 Basic Information

API Version: 2025-09-29
Protocol: HTTPS
Authentication: Bearer Token
Content Type: application/json

🔐 Authentication

All API requests must include a valid Bearer token:

Authorization: Bearer <your-api-token>

📋 Common Headers

Required Headers

Authorization: Bearer <token> - API authentication token
API-Version: 2025-09-29 - API version identifier
Content-Type: application/json - Request content type

Recommended Headers

Idempotency-Key: <unique-key> - Idempotency key
Request-Id: <correlation-id> - Request correlation ID
Accept-Language: en-US - Preferred language
User-Agent: <client-info> - Client information

Optional Headers (Security Enhancement)

Signature: <base64url-signature> - Request signature
Timestamp: <RFC3339-timestamp> - Request timestamp

🛒 Agentic Checkout API

Create Checkout Session

Create a new checkout session to initialize cart state.

POST /checkout_sessions

Request Body:

{
  "items": [
    {
      "id": "prod_12345",
      "quantity": 2
    }
  ],
  "buyer": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone_number": "+1-555-123-4567"
  },
  "fulfillment_address": {
    "name": "John Smith",
    "line_one": "1234 Chat Road",
    "line_two": "Suite 100",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94102"
  }
}

Response (201 Created):

{
  "id": "checkout_session_abc123",
  "payment_provider": {
    "provider": "stripe",
    "supported_payment_methods": ["card"]
  },
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "line_item_456",
      "item": {
        "id": "prod_12345",
        "quantity": 2
      },
      "base_amount": 5998,
      "discount": 600,
      "subtotal": 5398,
      "tax": 540,
      "total": 5938
    }
  ],
  "fulfillment_address": {
    "name": "John Smith",
    "line_one": "1234 Chat Road",
    "line_two": "Suite 100",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94102"
  },
  "fulfillment_option_id": "standard_shipping",
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "standard_shipping",
      "title": "Standard Shipping",
      "subtitle": "3-5 business days",
      "carrier": "USPS",
      "earliest_delivery_time": "2025-10-12T09:00:00Z",
      "latest_delivery_time": "2025-10-15T18:00:00Z",
      "subtotal": 1500,
      "tax": 0,
      "total": 1500
    },
    {
      "type": "shipping", 
      "id": "express_shipping",
      "title": "Express Shipping",
      "subtitle": "1-2 business days",
      "carrier": "FedEx",
      "earliest_delivery_time": "2025-10-10T09:00:00Z",
      "latest_delivery_time": "2025-10-11T18:00:00Z",
      "subtotal": 3000,
      "tax": 0,
      "total": 3000
    }
  ],
  "totals": [
    {
      "type": "items_base_amount",
      "display_text": "Items total",
      "amount": 5998
    },
    {
      "type": "items_discount",
      "display_text": "Discount",
      "amount": -600
    },
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 5398
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 1500
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 540
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 7438
    }
  ],
  "messages": [],
  "links": [
    {
      "type": "terms_of_use",
      "url": "https://acplib.com/legal/terms"
    },
    {
      "type": "privacy_policy", 
      "url": "https://acplib.com/legal/privacy"
    }
  ]
}

Update Checkout Session

Update an existing checkout session’s items, address, or fulfillment options.

POST /checkout_sessions/{checkout_session_id}

Request Body Example (update fulfillment option):

{
  "fulfillment_option_id": "express_shipping"
}

Request Body Example (update items):

{
  "items": [
    {
      "id": "prod_12345",
      "quantity": 3
    },
    {
      "id": "prod_67890", 
      "quantity": 1
    }
  ]
}

Response (200 OK): Returns updated complete session object

Retrieve Checkout Session

Get the current state of a checkout session.

GET /checkout_sessions/{checkout_session_id}

Response (200 OK): Returns complete session object

Complete Checkout Session

Complete checkout using payment information to create an order.

POST /checkout_sessions/{checkout_session_id}/complete

Request Body:

{
  "buyer": {
    "first_name": "John",
    "last_name": "Smith", 
    "email": "[email protected]",
    "phone_number": "+1-555-123-4567"
  },
  "payment_data": {
    "token": "vt_01J8Z3WXYZ9ABC",
    "provider": "stripe",
    "billing_address": {
      "name": "John Smith",
      "line_one": "1234 Chat Road",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94102"
    }
  }
}

Response (200 OK):

{
  "id": "checkout_session_abc123",
  "status": "completed",
  "order": {
    "id": "ord_xyz789",
    "checkout_session_id": "checkout_session_abc123",
    "permalink_url": "https://acplib.com/orders/ord_xyz789"
  },
  "currency": "usd",
  "line_items": [...],
  "totals": [...],
  "messages": [
    {
      "type": "info",
      "content_type": "plain",
      "content": "Order successfully created. We'll ship your items soon."
    }
  ]
}

Cancel Checkout Session

Cancel an uncompleted checkout session.

POST /checkout_sessions/{checkout_session_id}/cancel

Response (200 OK):

{
  "id": "checkout_session_abc123",
  "status": "canceled",
  "messages": [
    {
      "type": "info",
      "content_type": "plain", 
      "content": "Checkout session has been canceled."
    }
  ]
}

💳 Delegated Payment API

Create Delegated Payment Token

Create a delegated token for payment credentials for subsequent payment processing.

POST /agentic_commerce/delegate_payment

Request Body:

{
  "payment_method": {
    "type": "card",
    "card_number_type": "fpan",
    "virtual": false,
    "number": "4242424242424242",
    "exp_month": "12",
    "exp_year": "2026",
    "name": "John Smith",
    "cvc": "123",
    "checks_performed": ["avs", "cvv"],
    "iin": "424242",
    "display_card_funding_type": "credit",
    "display_wallet_type": null,
    "display_brand": "visa",
    "display_last4": "4242",
    "metadata": {
      "issuing_bank": "Chase Bank"
    }
  },
  "allowance": {
    "reason": "one_time",
    "max_amount": 7438,
    "currency": "usd",
    "checkout_session_id": "checkout_session_abc123",
    "merchant_id": "acplib_merchant",
    "expires_at": "2025-10-09T15:30:00Z"
  },
  "billing_address": {
    "name": "John Smith",
    "line_one": "1234 Chat Road",
    "line_two": "Suite 100",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94102"
  },
  "risk_signals": [
    {
      "type": "card_testing",
      "score": 15,
      "action": "authorized"
    }
  ],
  "metadata": {
    "source": "chatgpt",
    "session_id": "chat_session_123",
    "user_agent": "Mozilla/5.0..."
  }
}

Response (201 Created):

{
  "id": "vt_01J8Z3WXYZ9ABC",
  "created": "2025-09-29T11:00:00Z",
  "metadata": {
    "source": "agent_checkout",
    "merchant_id": "acplib_merchant",
    "idempotency_key": "idem_abc123"
  }
}

📊 Data Models

CheckoutSession Object

Field	Type	Description
`id`	string	Session unique identifier
`status`	enum	Session status: `not_ready_for_payment`, `ready_for_payment`, `completed`, `canceled`, `in_progress`
`currency`	string	ISO 4217 currency code (lowercase)
`line_items`	LineItem[]	Order line items list
`fulfillment_address`	Address	Shipping address
`fulfillment_options`	FulfillmentOption[]	Available shipping options
`fulfillment_option_id`	string	Selected shipping option ID
`totals`	Total[]	Amount summary list
`payment_provider`	PaymentProvider	Payment service provider info
`buyer`	Buyer	Buyer information
`messages`	Message[]	Message list
`links`	Link[]	Related links
`order`	Order	Order information (completed status only)

LineItem Object

Field	Type	Description
`id`	string	Line item unique identifier
`item`	Item	Product information
`base_amount`	integer	Base amount (minor units)
`discount`	integer	Discount amount (minor units)
`subtotal`	integer	Subtotal amount (minor units)
`tax`	integer	Tax amount (minor units)
`total`	integer	Total amount (minor units)

PaymentMethod Object

Field	Type	Required	Description
`type`	string	✅	Payment method type (currently only “card” supported)
`card_number_type`	enum	✅	Card number type: `fpan`, `network_token`
`virtual`	boolean	✅	Whether it’s a virtual card
`number`	string	✅	Card number/token
`exp_month`	string	❌	Expiry month (01-12)
`exp_year`	string	❌	Expiry year (four digits)
`name`	string	❌	Cardholder name
`cvc`	string	❌	Security code
`display_card_funding_type`	enum	✅	Card type: `credit`, `debit`, `prepaid`
`display_brand`	string	❌	Card brand (e.g., “visa”, “mastercard”)
`display_last4`	string	❌	Last four digits of card

⚠️ Error Handling

All error responses use a unified flat object format:

{
  "type": "invalid_request",
  "code": "missing_field",
  "message": "Missing required field 'items'",
  "param": "$.items"
}

Error Types

Type	HTTP Status	Description
`invalid_request`	400	Request format error or missing required fields
`request_not_idempotent`	409	Idempotency conflict
`processing_error`	422	Business logic processing error
`rate_limit_exceeded`	429	Request rate limit exceeded
`service_unavailable`	503	Service temporarily unavailable

Common Error Codes

Code	Description
`missing_field`	Missing required field
`invalid_field`	Invalid field value
`out_of_stock`	Product out of stock
`payment_declined`	Payment declined
`idempotency_conflict`	Idempotency key conflict
`session_not_found`	Session not found
`session_already_completed`	Session already completed

🔄 Idempotency

To ensure operation idempotency, it’s recommended to use the Idempotency-Key header in create and complete operations:

Idempotency-Key: unique-operation-key-123

Repeated requests with the same key and same parameters will return the same result
Requests with the same key but different parameters will return a 409 conflict error

📏 Limits and Constraints

Request Limits

Maximum request body size: 1MB
API call rate: 100 requests per second
Timeout: 30 seconds

Data Limits

Item quantity: Maximum 100 items per session
Address length: See Address object definition for field limits
Currency precision: Use integers in minor units

Session Lifecycle

Session validity: 24 hours
Payment token validity: Specified by allowance.expires_at
Maximum retry attempts: 3 times

Through following this API reference documentation, you can correctly implement all ACP protocol interfaces to ensure seamless integration with ChatGPT and other AI agents.

Delegated Payment Specification