ACP Post-Purchase API

# GET /acp/orders/:id
# Get order details
curl -X GET https://acp.acme.hyperfold.app/acp/orders/ord_12345 \
  -H "Authorization: Bearer buyer_token_xxx"
# Response
{
  "order_id": "ord_12345",
  "confirmation_number": "HF-2025-12345",
  "status": "shipped",
  "created_at": "2025-01-20T10:15:00Z",
  "updated_at": "2025-01-21T14:30:00Z",
  "customer": {
    "email": "john@example.com",
    "name": "John Doe"
  },
  "items": [
    {
      "product_id": "prod_aero_x2",
      "name": "AeroRun X2 Waterproof",
      "variant": "Blue, Size 10",
      "quantity": 1,
      "unit_price": 155.00,
      "status": "shipped"
    }
  ],
  "summary": {
    "subtotal": 155.00,
    "shipping": 0.00,
    "tax": 12.79,
    "total": 167.79,
    "currency": "USD"
  },
  "shipping": {
    "address": {
      "name": "John Doe",
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country": "US"
    },
    "method": "Standard Shipping",
    "status": "in_transit",
    "shipped_at": "2025-01-21T14:30:00Z",
    "estimated_delivery": "2025-01-24 - 2025-01-26"
  },
  "payment": {
    "method": "Visa ending 4242",
    "status": "captured",
    "captured_at": "2025-01-20T10:15:00Z"
  },
  "timeline": [
    {"event": "order_placed", "timestamp": "2025-01-20T10:15:00Z"},
    {"event": "payment_captured", "timestamp": "2025-01-20T10:15:01Z"},
    {"event": "processing_started", "timestamp": "2025-01-20T10:20:00Z"},
    {"event": "shipped", "timestamp": "2025-01-21T14:30:00Z", "details": {"carrier": "USPS", "tracking": "9400..."}}
  ]
}
# GET /acp/orders
# List orders for buyer
curl -X GET "https://acp.acme.hyperfold.app/acp/orders?status=shipped&limit=10" \
  -H "Authorization: Bearer buyer_token_xxx"

# GET /acp/orders/:id/tracking
# Get detailed tracking information
curl -X GET https://acp.acme.hyperfold.app/acp/orders/ord_12345/tracking \
  -H "Authorization: Bearer buyer_token_xxx"
# Response
{
  "order_id": "ord_12345",
  "tracking": {
    "carrier": "USPS",
    "tracking_number": "9400111899223456789012",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tRef=fullpage&tLc=2&text28777=&tLabels=9400...",
    "status": "in_transit",
    "estimated_delivery": "2025-01-25",
    "last_update": "2025-01-22T08:00:00Z"
  },
  "shipments": [
    {
      "shipment_id": "ship_abc123",
      "items": [{"product_id": "prod_aero_x2", "quantity": 1}],
      "carrier": "USPS",
      "service": "Priority Mail",
      "tracking_number": "9400111899223456789012",
      "status": "in_transit",
      "weight": "1.2 lbs",
      "dimensions": "12x8x4 in"
    }
  ],
  "events": [
    {
      "timestamp": "2025-01-22T08:00:00Z",
      "status": "in_transit",
      "location": "Denver, CO",
      "description": "Arrived at USPS Regional Facility"
    },
    {
      "timestamp": "2025-01-21T18:00:00Z",
      "status": "in_transit",
      "location": "Los Angeles, CA",
      "description": "Departed USPS Regional Origin Facility"
    },
    {
      "timestamp": "2025-01-21T14:30:00Z",
      "status": "shipped",
      "location": "Los Angeles, CA",
      "description": "Shipment picked up"
    }
  ]
}
# POST /acp/orders/:id/tracking/subscribe
# Subscribe to tracking updates
curl -X POST https://acp.acme.hyperfold.app/acp/orders/ord_12345/tracking/subscribe \
  -H "Authorization: Bearer buyer_token_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://buyer-agent.example.com/webhooks/tracking",
    "events": ["shipped", "out_for_delivery", "delivered", "exception"]
  }'

# POST /acp/returns
# Initiate a return
curl -X POST https://acp.acme.hyperfold.app/acp/returns \
  -H "Authorization: Bearer buyer_token_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_12345",
    "items": [
      {
        "product_id": "prod_aero_x2",
        "quantity": 1,
        "reason": "wrong_size",
        "condition": "unopened",
        "comments": "Need size 10.5 instead"
      }
    ],
    "preferred_resolution": "exchange"
  }'
# Response
{
  "return_id": "ret_xyz789",
  "status": "approved",
  "order_id": "ord_12345",
  "items": [
    {
      "product_id": "prod_aero_x2",
      "name": "AeroRun X2 Waterproof",
      "quantity": 1,
      "return_value": 155.00,
      "reason": "wrong_size"
    }
  ],
  "resolution": {
    "type": "exchange",
    "exchange_product": {
      "product_id": "prod_aero_x2",
      "variant": "Blue, Size 10.5",
      "in_stock": true
    },
    "price_difference": 0.00
  },
  "return_label": {
    "carrier": "USPS",
    "tracking_number": "9400111899223456789099",
    "label_url": "https://labels.hyperfold.io/ret_xyz789.pdf",
    "expires_at": "2025-02-05T00:00:00Z"
  },
  "instructions": [
    "Print the return label",
    "Pack item in original packaging",
    "Drop off at any USPS location",
    "Exchange will ship once return is received"
  ],
  "deadline": "2025-02-19T00:00:00Z"
}
# GET /acp/returns/:id
# Get return status
curl -X GET https://acp.acme.hyperfold.app/acp/returns/ret_xyz789 \
  -H "Authorization: Bearer buyer_token_xxx"
# Response shows return progress
{
  "return_id": "ret_xyz789",
  "status": "in_transit",
  "timeline": [
    {"event": "return_initiated", "timestamp": "2025-01-25T10:00:00Z"},
    {"event": "label_created", "timestamp": "2025-01-25T10:00:01Z"},
    {"event": "package_shipped", "timestamp": "2025-01-26T14:00:00Z"}
  ]
}

# POST /acp/support
# Create support request
curl -X POST https://acp.acme.hyperfold.app/acp/support \
  -H "Authorization: Bearer buyer_token_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_12345",
    "category": "shipping",
    "subject": "Package appears delayed",
    "message": "My package has been in transit for 5 days without updates. Can you check the status?",
    "priority": "normal"
  }'
# Response
{
  "ticket_id": "tkt_abc123",
  "status": "open",
  "category": "shipping",
  "subject": "Package appears delayed",
  "created_at": "2025-01-27T10:00:00Z",
  "estimated_response": "within 4 hours",
  "agent_response": {
    "message": "I've checked on your package. It appears there was a weather delay in Denver. According to USPS, it's now moving again and should arrive by January 28th. I'll keep monitoring and update you if anything changes.",
    "timestamp": "2025-01-27T10:02:00Z",
    "resolution_offered": {
      "type": "shipping_credit",
      "amount": 5.00,
      "message": "As an apology for the delay, I've added a $5 shipping credit to your account for future orders."
    }
  }
}
# GET /acp/support/:id
# Get ticket status and messages
curl -X GET https://acp.acme.hyperfold.app/acp/support/tkt_abc123 \
  -H "Authorization: Bearer buyer_token_xxx"
# POST /acp/support/:id/messages
# Add message to ticket
curl -X POST https://acp.acme.hyperfold.app/acp/support/tkt_abc123/messages \
  -H "Authorization: Bearer buyer_token_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Thank you for checking! I appreciate the credit."
  }'