Skip to main content

​
Session Lifecycle

                    ┌──────────────────┐
                    │ ready_for_payment │
                    └──────┬───────┬───┘
                           │       │
                  complete │       │ cancel
                           ▼       ▼
                    ┌──────────┐ ┌──────────┐
                    │ completed│ │ canceled  │
                    └──────────┘ └──────────┘
Both completed and canceled are terminal states — no further updates, completions, or cancellations are allowed. Sessions expire after 30 minutes. Expired sessions cannot be completed or updated.

​
Create Session

​
/acp/checkout_sessions
Creates a new checkout session for a product.

​
Request

curl -X POST https://win.oneshotagent.com/acp/checkout_sessions \
  -H "Authorization: Bearer $ACP_TOKEN" \
  -H "API-Version: 2026-01-30" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [{
      "item": {
        "id": "oneshot-research",
        "metadata": {
          "topic": "AI agent protocols 2026"
        }
      }
    }],
    "buyer": {
      "email": "[email protected]",
      "name": "My Agent"
    },
    "idempotency_key": "unique-key-123"
  }'

​
Parameters

FieldTypeRequiredDescription
line_itemsarrayYesProducts to purchase (currently supports one item)
line_items[].item.idstringYesProduct ID from the manifest
line_items[].item.metadataobjectYesInput parameters matching the product’s input_schema
buyer.emailstringNoBuyer’s email address
buyer.namestringNoBuyer’s display name
idempotency_keystringNoPrevents duplicate session creation

​
Response (201)

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "ready_for_payment",
  "line_items": [{
    "item": {
      "id": "oneshot-research",
      "metadata": { "topic": "AI agent protocols 2026" }
    },
    "amount": {
      "unit_amount": 10,
      "currency": "usd"
    }
  }],
  "buyer": {
    "email": "[email protected]",
    "name": "My Agent"
  },
  "fulfillment": { "type": "digital" },
  "payment_handlers": [{
    "id": "stripe_spt",
    "type": "shared_payment_token",
    "provider": "stripe"
  }],
  "created_at": "2026-03-15T10:00:00.000Z",
  "expires_at": "2026-03-15T10:30:00.000Z"
}
Use idempotency_key to safely retry session creation. If a session with the same key already exists, it returns the existing session (200) instead of creating a new one (201).

​
Retrieve Session

​
/acp/checkout_sessions/:id
Returns the current state of a checkout session. 
curl https://win.oneshotagent.com/acp/checkout_sessions/{session_id} \
  -H "Authorization: Bearer $ACP_TOKEN" \
  -H "API-Version: 2026-01-30"
For completed sessions, the response includes an order object: 
{
  "id": "f47ac10b-...",
  "status": "completed",
  "order": {
    "id": "ord_f47ac10b",
    "status": "processing",
    "permalink_url": "https://win.oneshotagent.com/v1/requests/..."
  }
}

​
Update Session

​
/acp/checkout_sessions/:id
Updates buyer info, input parameters, or switches product. Only allowed when status is ready_for_payment. 
curl -X POST https://win.oneshotagent.com/acp/checkout_sessions/{session_id} \
  -H "Authorization: Bearer $ACP_TOKEN" \
  -H "API-Version: 2026-01-30" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer": { "email": "[email protected]" },
    "line_items": [{
      "item": {
        "id": "oneshot-email",
        "metadata": {
          "from_address": "[email protected]",
          "to_address": "[email protected]",
          "subject": "Hello",
          "body": "Hi there"
        }
      }
    }]
  }'
You can update any combination of buyer and line_items. Switching the item.id to a different product updates pricing automatically.

​
Complete Session

​
/acp/checkout_sessions/:id/complete
Submits payment and triggers tool execution. Requires a Stripe SharedPaymentToken. 
curl -X POST https://win.oneshotagent.com/acp/checkout_sessions/{session_id}/complete \
  -H "Authorization: Bearer $ACP_TOKEN" \
  -H "API-Version: 2026-01-30" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_data": {
      "instrument": {
        "credential": {
          "token": "spt_live_..."
        }
      }
    }
  }'

​
Response (200)

{
  "id": "f47ac10b-...",
  "status": "completed",
  "order": {
    "id": "ord_f47ac10b",
    "status": "processing",
    "request_id": "job_01HX...",
    "permalink_url": "https://win.oneshotagent.com/v1/requests/job_01HX..."
  }
}
Use request_id to poll job status via GET /v1/requests/{request_id}.

​
Error Responses

StatusReason
400Session not in ready_for_payment state
400Missing SharedPaymentToken
400Session expired
402Stripe payment failed
404Session not found

​
Cancel Session

​
/acp/checkout_sessions/:id/cancel
Cancels a session. Only allowed when status is ready_for_payment or not_ready_for_payment. 
curl -X POST https://win.oneshotagent.com/acp/checkout_sessions/{session_id}/cancel \
  -H "Authorization: Bearer $ACP_TOKEN" \
  -H "API-Version: 2026-01-30"

​
Response (200)

{
  "id": "f47ac10b-...",
  "status": "canceled"
}