ACP Commerce API

# 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"
}

# 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"
}

# 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
}

# 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"
}