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": "john.doe@example.com",
"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"
}
}'
const checkout = await stateset.checkouts.create({
items: [
{
id: "item_123",
quantity: 2
}
],
buyer: {
first_name: "John",
last_name: "Doe",
email: "john.doe@example.com",
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"
}
});
checkout = stateset.checkouts.create(
items=[
{
"id": "item_123",
"quantity": 2
}
],
buyer={
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"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": "john.doe@example.com",
"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": []
}
{
"success": false,
"error": {
"type": "invalid_request",
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": {
"items": "At least one item is required",
"buyer.email": "Invalid email format"
}
}
}
Create Checkout Session
Create a new checkout session with buyer details, line items, and shipping information
POST
/
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": "john.doe@example.com",
"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"
}
}'
const checkout = await stateset.checkouts.create({
items: [
{
id: "item_123",
quantity: 2
}
],
buyer: {
first_name: "John",
last_name: "Doe",
email: "john.doe@example.com",
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"
}
});
checkout = stateset.checkouts.create(
items=[
{
"id": "item_123",
"quantity": 2
}
],
buyer={
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"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": "john.doe@example.com",
"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": []
}
{
"success": false,
"error": {
"type": "invalid_request",
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": {
"items": "At least one item is required",
"buyer.email": "Invalid email format"
}
}
}
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 withcheckouts:write permissions.
Authorization: Bearer YOUR_API_KEY
Request Body
array
required
object
object
Address where the order will ship
Show Address properties
Show Address properties
string
required
Name of the person receiving the items
string
required
Street address line 1
string
Street address line 2 (apartment, suite, etc.)
string
required
City name
string
required
State or province code
string
required
ISO 3166-1 alpha-2 country code (e.g., “US”, “CA”)
string
required
Postal or ZIP code
Response
string
Unique identifier for the Checkout Session
object
Information about the buyer
object
Payment provider configuration and supported payment methods
string
Current status:
not_ready_for_payment, ready_for_payment, completed, canceled, in_progressstring
Three-letter ISO currency code in lowercase
array
Array of line items in the checkout with calculated amounts
object
Address where the order will ship
array
Available shipping and fulfillment options
string
ID of the currently selected fulfillment option
array
Breakdown of charges including subtotal, tax, shipping, and total
array
Array of messages or notifications related to the checkout
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": "john.doe@example.com",
"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"
}
}'
const checkout = await stateset.checkouts.create({
items: [
{
id: "item_123",
quantity: 2
}
],
buyer: {
first_name: "John",
last_name: "Doe",
email: "john.doe@example.com",
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"
}
});
checkout = stateset.checkouts.create(
items=[
{
"id": "item_123",
"quantity": 2
}
],
buyer={
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"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": "john.doe@example.com",
"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": []
}
{
"success": false,
"error": {
"type": "invalid_request",
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": {
"items": "At least one item is required",
"buyer.email": "Invalid email format"
}
}
}
⌘I