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
Address where the order will ship
Show Address properties
Show Address properties
Name of the person receiving the items
Street address line 1
Street address line 2 (apartment, suite, etc.)
City name
State or province code
ISO 3166-1 alpha-2 country code (e.g., “US”, “CA”)
Postal or ZIP code
Response
Unique identifier for the Checkout Session
Information about the buyer
Payment provider configuration and supported payment methods
Current status:
not_ready_for_payment, ready_for_payment, completed, canceled, in_progressThree-letter ISO currency code in lowercase
Array of line items in the checkout with calculated amounts
Address where the order will ship
Available shipping and fulfillment options
ID of the currently selected fulfillment option
Breakdown of charges including subtotal, tax, shipping, and total
Array of messages or notifications related to the checkout
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