Skip to main content
POST
https://api.stateset.com
/
v1
/
checkouts
curl -X POST https://api.stateset.com/v1/checkouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "item_123",
        "quantity": 2
      }
    ],
    "buyer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "+1234567890"
    },
    "fulfillment_address": {
      "name": "John Doe",
      "line_one": "123 Main St",
      "line_two": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94105"
    }
  }'

{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+1234567890"
  },
  "payment_provider": {
    "provider": "stripe",
    "supported_payment_methods": ["card"]
  },
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 2
      },
      "base_amount": 2000,
      "discount": 0,
      "total": 2000,
      "subtotal": 2000,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "123 Main St",
    "line_two": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 2000
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 2250
    }
  ],
  "messages": [],
  "links": []
}
This endpoint creates a new Checkout Session for the Agentic Commerce Protocol, enabling AI agents to manage commerce transactions. The session tracks buyer information, cart items, and fulfillment options.

​
Authentication

This endpoint requires a valid API key with checkouts:write permissions. 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
items
array
required
Array of items to purchase
​
buyer
object
Information about the buyer
​
fulfillment_address
object
Address where the order will ship

​
Response

​
id
string
Unique identifier for the Checkout Session
​
buyer
object
Information about the buyer
​
payment_provider
object
Payment provider configuration and supported payment methods
​
status
string
Current status: not_ready_for_payment, ready_for_payment, completed, canceled, in_progress
​
currency
string
Three-letter ISO currency code in lowercase
​
line_items
array
Array of line items in the checkout with calculated amounts
​
fulfillment_address
object
Address where the order will ship
​
fulfillment_options
array
Available shipping and fulfillment options
​
fulfillment_option_id
string
ID of the currently selected fulfillment option
​
totals
array
Breakdown of charges including subtotal, tax, shipping, and total
​
messages
array
Array of messages or notifications related to the checkout
​
links
array
Array of links related to policies and agreements
curl -X POST https://api.stateset.com/v1/checkouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "item_123",
        "quantity": 2
      }
    ],
    "buyer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "+1234567890"
    },
    "fulfillment_address": {
      "name": "John Doe",
      "line_one": "123 Main St",
      "line_two": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94105"
    }
  }'

{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+1234567890"
  },
  "payment_provider": {
    "provider": "stripe",
    "supported_payment_methods": ["card"]
  },
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 2
      },
      "base_amount": 2000,
      "discount": 0,
      "total": 2000,
      "subtotal": 2000,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "123 Main St",
    "line_two": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 2000
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 2250
    }
  ],
  "messages": [],
  "links": []
}