Hyperfold AI

ACP Commerce API

Negotiate prices and complete purchases through the Agentic Commerce Protocol.

Overview

The ACP Commerce API handles the core transaction flow: price negotiation, checkout initialization, and order completion. These endpoints enable autonomous agent-to-agent commerce.

EndpointPurpose
POST /acp/quoteRequest quote and negotiate price
POST /acp/checkout/initInitialize checkout session
POST /acp/checkout/finalizeComplete purchase
GET /acp/sessions/:idGet session details

Quote & Negotiate

The quote endpoint handles price negotiation between buyer and seller agents:

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
# POST /acp/quote
# Request price quote and negotiate
 
curl -X POST https://acp.acme.hyperfold.app/acp/quote \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "product_id": "prod_aero_x2",
    "variant_id": "var_blue_10",
    "quantity": 1,
    "offer_price": 150.00,
    "buyer_context": {
      "loyalty_tier": "gold",
      "purchase_history": 12,
      "urgency": "flexible"
    }
  }'
 
# Response - Counter Offer
{
  "status": "counter_offer",
  "session_id": "sess_abc123",
  "quote_id": "quote_xyz789",
  "product": {
    "id": "prod_aero_x2",
    "name": "AeroRun X2 Waterproof"
  },
  "original_price": 179.99,
  "your_offer": 150.00,
  "counter_price": 162.00,
  "discount_applied": "10%",
  "reasoning": "I can offer you our Gold member price of $162. This includes a 10% loyalty discount, which is our best available rate for this premium shoe.",
  "valid_until": "2025-01-20T12:00:00Z",
  "bundle_suggestion": {
    "product_id": "prod_socks_wp",
    "name": "Waterproof Running Socks",
    "regular_price": 29.99,
    "bundle_price": 24.99,
    "bundle_total": 179.99,
    "total_savings": 30.00
  },
  "next_actions": ["accept", "counter", "decline", "add_bundle"]
}
 
# Follow-up negotiation
curl -X POST https://acp.acme.hyperfold.app/acp/quote \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "quote_id": "quote_xyz789",
    "offer_price": 155.00,
    "message": "Can you do $155? I am buying for my marathon next month."
  }'
 
# Response - Accept
{
  "status": "accept",
  "session_id": "sess_abc123",
  "quote_id": "quote_xyz789",
  "final_price": 155.00,
  "message": "Deal! I can do $155 for you since you're training for a marathon. Good luck with your race!",
  "valid_until": "2025-01-20T12:00:00Z",
  "checkout_token": "chk_token_abc123"
}

Quote Response Statuses

StatusDescription
acceptOffer accepted, proceed to checkout
counter_offerCounter price proposed
rejectOffer rejected, floor price hinted
expiredPrevious quote expired

Initialize Checkout

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
# POST /acp/checkout/init
# Initialize checkout session
 
curl -X POST https://acp.acme.hyperfold.app/acp/checkout/init \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "checkout_token": "chk_token_abc123",
    "items": [
      {
        "product_id": "prod_aero_x2",
        "variant_id": "var_blue_10",
        "quantity": 1,
        "negotiated_price": 155.00
      }
    ],
    "shipping_address": {
      "name": "John Doe",
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country": "US",
      "phone": "+1-555-123-4567"
    },
    "billing_same_as_shipping": true
  }'
 
# Response
{
  "checkout_id": "chk_xyz789",
  "status": "ready",
  "summary": {
    "subtotal": 155.00,
    "shipping": 0.00,
    "tax": 12.79,
    "total": 167.79,
    "savings": 24.99,
    "currency": "USD"
  },
  "items": [
    {
      "product_id": "prod_aero_x2",
      "name": "AeroRun X2 Waterproof",
      "variant": "Blue, Size 10",
      "quantity": 1,
      "unit_price": 155.00,
      "original_price": 179.99,
      "discount": 24.99
    }
  ],
  "shipping_options": [
    {
      "id": "standard",
      "name": "Standard Shipping",
      "price": 0.00,
      "estimate": "3-5 business days",
      "selected": true
    },
    {
      "id": "express",
      "name": "Express Shipping",
      "price": 12.99,
      "estimate": "1-2 business days"
    }
  ],
  "payment_methods": [
    {"type": "stripe_spt", "ready": true},
    {"type": "paypal_ba", "ready": true}
  ],
  "valid_until": "2025-01-20T11:30:00Z"
}

Finalize Checkout

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
# POST /acp/checkout/finalize
# Complete purchase with payment token
 
curl -X POST https://acp.acme.hyperfold.app/acp/checkout/finalize \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_id": "chk_xyz789",
    "payment": {
      "method": "stripe_spt",
      "token": "spt_live_abc123..."
    },
    "shipping_option": "standard",
    "buyer_email": "john@example.com",
    "notes": "Please leave at the front door"
  }'
 
# Response - Success
{
  "status": "success",
  "order": {
    "id": "ord_12345",
    "confirmation_number": "HF-2025-12345",
    "status": "confirmed",
    "created_at": "2025-01-20T10:15:00Z"
  },
  "payment": {
    "id": "pay_abc123",
    "status": "succeeded",
    "amount": 167.79,
    "currency": "USD",
    "method": "Visa ending 4242"
  },
  "fulfillment": {
    "status": "processing",
    "estimated_ship_date": "2025-01-21",
    "estimated_delivery": "2025-01-24 - 2025-01-26"
  },
  "receipt_url": "https://receipts.hyperfold.io/ord_12345",
  "tracking": {
    "available": false,
    "url": null,
    "message": "Tracking info will be available once shipped"
  },
  "summary": {
    "items": [{"name": "AeroRun X2 Waterproof", "quantity": 1, "price": 155.00}],
    "subtotal": 155.00,
    "shipping": 0.00,
    "tax": 12.79,
    "total": 167.79
  }
}
 
# Response - Payment Failed
{
  "status": "payment_failed",
  "error": {
    "code": "card_declined",
    "message": "Your card was declined. Please try a different payment method.",
    "decline_code": "insufficient_funds"
  },
  "checkout_id": "chk_xyz789",
  "checkout_status": "pending",
  "retry_allowed": true
}

Payment Methods

MethodToken Format
stripe_sptStripe Shared Payment Token
paypal_baPayPal Billing Agreement
Payment tokens are provided by the buyer agent and represent pre-authorized payment credentials. See Shared Payment Tokens.

Session Management

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
# GET /acp/sessions/:id
# Get session details and history
 
curl -X GET https://acp.acme.hyperfold.app/acp/sessions/sess_abc123
 
# Response
{
  "session_id": "sess_abc123",
  "status": "active",
  "created_at": "2025-01-20T10:00:00Z",
  "last_activity": "2025-01-20T10:15:00Z",
  "expires_at": "2025-01-20T11:00:00Z",
  "buyer_context": {
    "loyalty_tier": "gold",
    "purchase_history": 12
  },
  "cart": {
    "items": [
      {
        "product_id": "prod_aero_x2",
        "name": "AeroRun X2 Waterproof",
        "quantity": 1,
        "negotiated_price": 155.00
      }
    ],
    "subtotal": 155.00
  },
  "negotiation_history": [
    {
      "timestamp": "2025-01-20T10:05:00Z",
      "type": "quote_request",
      "offer": 150.00,
      "response": "counter_offer",
      "counter": 162.00
    },
    {
      "timestamp": "2025-01-20T10:10:00Z",
      "type": "quote_request",
      "offer": 155.00,
      "response": "accept",
      "final_price": 155.00
    }
  ],
  "recommendations_shown": [
    {"product_id": "prod_socks_wp", "accepted": false}
  ]
}
 
# POST /acp/sessions/:id/extend
# Extend session expiration
 
curl -X POST https://acp.acme.hyperfold.app/acp/sessions/sess_abc123/extend \
  -H "Content-Type: application/json" \
  -d '{"duration_minutes": 30}'
 
# Response
{
  "session_id": "sess_abc123",
  "new_expires_at": "2025-01-20T11:30:00Z"
}
After purchase, use the Post-Purchase API for order tracking and returns.