Checkout Sessions

curl --request POST \
  --url https://win.oneshotagent.com/acp/checkout_sessions

const options = {method: 'POST'};

fetch('https://win.oneshotagent.com/acp/checkout_sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://win.oneshotagent.com/acp/checkout_sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://win.oneshotagent.com/acp/checkout_sessions"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://win.oneshotagent.com/acp/checkout_sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

acp

checkout_sessions

Checkout Sessions

curl --request POST \
  --url https://win.oneshotagent.com/acp/checkout_sessions

const options = {method: 'POST'};

fetch('https://win.oneshotagent.com/acp/checkout_sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://win.oneshotagent.com/acp/checkout_sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://win.oneshotagent.com/acp/checkout_sessions"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://win.oneshotagent.com/acp/checkout_sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

All paid endpoints on this page accept optional memo (≤ 1000 chars) and decisionContext (object) body fields. Stored on the receipt for debugging and audit — see Audit Trail.

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

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

Field	Type	Required	Description
`line_items`	array	Yes	Products to purchase (currently supports one item)
`line_items[].item.id`	string	Yes	Product ID from the manifest
`line_items[].item.metadata`	object	Yes	Input parameters matching the product’s `input_schema`
`buyer.email`	string	No	Buyer’s email address
`buyer.name`	string	No	Buyer’s display name
`idempotency_key`	string	No	Prevents 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

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

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

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

Status	Reason
400	Session not in `ready_for_payment` state
400	Missing SharedPaymentToken
400	Session expired
402	Stripe payment failed
404	Session not found

Cancel Session

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

Manifest

​Session Lifecycle

​Create Session

​Request

​Parameters

​Response (201)

​Retrieve Session

​Update Session

​Complete Session

​Response (200)

​Error Responses

​Cancel Session

​Response (200)

Session Lifecycle

Create Session

Request

Parameters

Response (201)

Retrieve Session

Update Session

Complete Session

Response (200)

Error Responses

Cancel Session

Response (200)