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

A checkout session prices one tool call, takes payment, and runs the tool. Create it, update it if the input changes, then complete or cancel it within 30 minutes. Completing it returns a request_id you poll for results.

Paid endpoints on this page accept optional memo (≤ 1000 chars) and decisionContext (object) body fields. Both are stored on the receipt for debugging and audit. See Audit Trail.

Session Lifecycle

A new session is ready_for_payment. It ends in one of two terminal states.

                    ┌──────────────────┐
                    │ ready_for_payment │
                    └──────┬───────┬───┘
                           │       │
                  complete │       │ cancel
                           ▼       ▼
                    ┌──────────┐ ┌──────────┐
                    │ completed│ │ canceled  │
                    └──────────┘ └──────────┘

completed and canceled are terminal: a session in either state can’t be updated, completed, or canceled. Sessions expire after 30 minutes. An expired session can’t be completed or updated.

Create Session

Creates a checkout session for one product and returns its exact price.

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 retry session creation safely. If a session with the same key exists, the API returns it (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

Changes buyer info or input parameters, or switches product. Allowed only while 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"
        }
      }
    }]
  }'

Send buyer, line_items, or both. Changing item.id to another product updates the price.

Complete Session

Charges a Stripe SharedPaymentToken and starts the tool. Returns an order with a request_id.

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

Poll job status with GET /v1/requests/{request_id}, using the returned request_id.

Error Responses

Check order.status even on HTTP 200. If payment succeeds but the tool fails, completion returns HTTP 200 with status: "completed" and order.status: "failed". The order carries error_code (one of the codes below) and error (the generic message). Validation errors and caught payment or execution failures include a machine-readable code and a human-readable message. Branch on code, not on the text of message:

Code	Meaning
`payment`	Payment could not be processed
`validation`	Request parameters are invalid
`internal`	An internal operation failed
`upstream`	A required service is unavailable, timed out, or rate limited

Caught exceptions return a generic message, not provider error details:

{
  "type": "payment_error",
  "code": "payment",
  "message": "Payment could not be processed. Check your payment method and try again."
}

A missing session returns 404 with type: "not_found" and message: "Session not found", without a code.

Status	Reason
400	Session not in `ready_for_payment` state
400	Missing SharedPaymentToken
400	Session expired
402	Stripe payment failed
404	Session not found
502	Upstream service or Stripe rate limit/timeout

Cancel Session

Cancels a session. Allowed only while 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"
}

​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)