Hyperfold AI

ACP Post-Purchase API

Order tracking, returns, and customer support endpoints.

Overview

The Post-Purchase API handles everything after checkout: order status, shipment tracking, returns processing, and customer support. These endpoints enable buyer agents to manage purchases on behalf of their users.

EndpointPurpose
/acp/orders/:idOrder details and status
/acp/orders/:id/trackingShipment tracking
/acp/returnsReturn requests
/acp/supportCustomer support tickets

Order Status

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

Order Statuses

StatusDescription
confirmedOrder placed, payment captured
processingBeing prepared for shipment
shippedHanded to carrier
deliveredSuccessfully delivered
cancelledOrder cancelled

Tracking

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

Returns

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

Return Reasons

ReasonAuto-Approve
wrong_sizeYes (if within policy)
defectiveYes
not_as_describedReview required
changed_mindYes (restocking fee may apply)

Support

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
# 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."
  }'
Support requests are handled by agents with escalation to human support when necessary. Response times vary by priority and complexity.
You've completed the ACP API documentation! Return to API Overview for management APIs.