> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Checkout Session

> Create a new checkout session with buyer details, line items, and shipping information

<Note>
  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.
</Note>

## Authentication

This endpoint requires a valid API key with `checkouts:write` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

<ParamField body="items" type="array" required>
  Array of items to purchase

  <Expandable title="Item object properties">
    <ParamField body="id" type="string" required>
      Unique identifier for the item
    </ParamField>

    <ParamField body="quantity" type="integer" required>
      Requested quantity of the item
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="buyer" type="object">
  Information about the buyer

  <Expandable title="Buyer properties">
    <ParamField body="first_name" type="string" required>
      First name of the buyer
    </ParamField>

    <ParamField body="last_name" type="string" required>
      Last name of the buyer
    </ParamField>

    <ParamField body="email" type="string" required>
      Email address of the buyer
    </ParamField>

    <ParamField body="phone_number" type="string">
      Phone number of the buyer (E.164 format recommended)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="fulfillment_address" type="object">
  Address where the order will ship

  <Expandable title="Address properties">
    <ParamField body="name" type="string" required>
      Name of the person receiving the items
    </ParamField>

    <ParamField body="line_one" type="string" required>
      Street address line 1
    </ParamField>

    <ParamField body="line_two" type="string">
      Street address line 2 (apartment, suite, etc.)
    </ParamField>

    <ParamField body="city" type="string" required>
      City name
    </ParamField>

    <ParamField body="state" type="string" required>
      State or province code
    </ParamField>

    <ParamField body="country" type="string" required>
      ISO 3166-1 alpha-2 country code (e.g., "US", "CA")
    </ParamField>

    <ParamField body="postal_code" type="string" required>
      Postal or ZIP code
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique identifier for the Checkout Session
</ResponseField>

<ResponseField name="buyer" type="object">
  Information about the buyer
</ResponseField>

<ResponseField name="payment_provider" type="object">
  Payment provider configuration and supported payment methods
</ResponseField>

<ResponseField name="status" type="string">
  Current status: `not_ready_for_payment`, `ready_for_payment`, `completed`, `canceled`, `in_progress`
</ResponseField>

<ResponseField name="currency" type="string">
  Three-letter ISO currency code in lowercase
</ResponseField>

<ResponseField name="line_items" type="array">
  Array of line items in the checkout with calculated amounts
</ResponseField>

<ResponseField name="fulfillment_address" type="object">
  Address where the order will ship
</ResponseField>

<ResponseField name="fulfillment_options" type="array">
  Available shipping and fulfillment options
</ResponseField>

<ResponseField name="fulfillment_option_id" type="string">
  ID of the currently selected fulfillment option
</ResponseField>

<ResponseField name="totals" type="array">
  Breakdown of charges including subtotal, tax, shipping, and total
</ResponseField>

<ResponseField name="messages" type="array">
  Array of messages or notifications related to the checkout
</ResponseField>

<ResponseField name="links" type="array">
  Array of links related to policies and agreements
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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"
    }
  });
  ```

  ```python Python theme={null}
  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"
      }
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "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": []
  }
  ```

  ```json Error Response - Validation Error theme={null}
  {
    "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"
      }
    }
  }
  ```
</ResponseExample>