# Build the Agentic Commerce Protocol checkout endpoints

Learn about the Agentic Commerce Protocol specification.

You can use the Agentic Commerce Protocol (ACP) to enable AI agents to manage commerce transactions between buyers and sellers. This specification defines the methods and data structures for creating, updating, and completing checkout flows.

You can find examples for REST integrations below.

## Create a Checkout Session 

You can create a new Checkout Session with buyer details, line items, and shipping information.

### Request 

Specify the parameters required for your request.

| Parameter                | Type                                                                                                          | Description                                 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| **items**                | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#item)              | Array of items you can purchase. (Required) |
| **buyer**                | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)   | Information about the buyer.                |
| **fulfillment\_address** | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address) | Address where the order will ship.          |

**Example request:**

```json
POST /checkouts
{
  "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"
  }
}
```

### Response 

The response returns the current state of the checkout from the seller.

| Parameter                   | Type                                                                                                                   | Description                                                                                                                                                     |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id**                      | `string`                                                                                                               | Unique identifier for the Checkout Session. (Required)                                                                                                          |
| **buyer**                   | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)            | Information about the buyer.                                                                                                                                    |
| **payment\_provider**       | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#payment-provider) | Payment provider configuration and supported payment methods.                                                                                                   |
| **status**                  | `string`                                                                                                               | Current status of the checkout process. (Required)

  Possible values: `not_ready_for_payment` | `ready_for_payment` | `completed` | `canceled` | `in_progress` |
| **currency**                | `string`                                                                                                               | Three-letter ISO currency code, in lowercase. (Required)                                                                                                        |
| **line\_items**             | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#line-item)                  | Array of line items in the checkout process. (Required)                                                                                                         |
| **fulfillment\_address**    | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address)          | Address where the order will ship.                                                                                                                              |
| **fulfillment\_options**    | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#fulfillment-option)         | Available shipping and fulfillment options. (Required)                                                                                                          |
| **fulfillment\_option\_id** | `string` (optional)                                                                                                    | ID of the currently selected fulfillment option.                                                                                                                |
| **totals**                  | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#total)                      | Overview of charges and discounts. (Required)                                                                                                                   |
| **messages**                | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#message)                    | Array of messages or notifications related to the checkout process. (Required)                                                                                  |
| **links**                   | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#link)                       | Array of links related to the checkout process. (Required)                                                                                                      |

**Example response:**

```json
{
  "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": []
}
```

## Retrieve a Checkout object 

To retrieve an existing Checkout Session using its ID, make a request to the appropriate API endpoint with the ID included in the request.

### Request 

Specify the parameters required for your request.

| Parameter | Type     | Description                                            |
| --------- | -------- | ------------------------------------------------------ |
| **id**    | `string` | Unique identifier for the checkout process. (Required) |

**Example request:**

```json
GET /checkouts/:id
```

### Response 

The response returns the current state of the checkout from the seller.

| Parameter                   | Type                                                                                                                   | Description                                                                                                                                                     |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id**                      | `string`                                                                                                               | Unique identifier for the checkout session. (Required)                                                                                                          |
| **buyer**                   | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)            | Information about the buyer.                                                                                                                                    |
| **payment\_provider**       | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#payment-provider) | Payment provider configuration and supported payment methods.                                                                                                   |
| **status**                  | `string`                                                                                                               | Current status of the checkout process. (Required)

  Possible values: `not_ready_for_payment` | `ready_for_payment` | `completed` | `canceled` | `in_progress` |
| **currency**                | `string`                                                                                                               | Three-letter ISO currency code, in lowercase. (Required)                                                                                                        |
| **line\_items**             | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#line-item)                  | Array of line items in the checkout process. (Required)                                                                                                         |
| **fulfillment\_address**    | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address)          | Address where the order will ship.                                                                                                                              |
| **fulfillment\_options**    | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#fulfillment-option)         | Available shipping and fulfillment options. (Required)                                                                                                          |
| **fulfillment\_option\_id** | `string` (optional)                                                                                                    | ID of the currently selected fulfillment option.                                                                                                                |
| **totals**                  | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#total)                      | Overview of charges and discounts. (Required)                                                                                                                   |
| **messages**                | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#message)                    | Array of messages or notifications related to the checkout process. (Required)                                                                                  |
| **links**                   | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#link)                       | Array of links related to the checkout process. (Required)                                                                                                      |

**Example response:**

```json
{
  "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": []
}
```

## Update a Checkout Session 

You can update an existing Checkout Session by modifying line items, shipping address, or fulfillment options.

### Request 

Specify the parameters required for your request.

| Parameter                   | Type                                                                                                          | Description                                            |
| --------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **id**                      | `string`                                                                                                      | Unique identifier for the checkout process. (Required) |
| **buyer**                   | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)   | Information about the buyer.                           |
| **items**                   | `array` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#item)   | Updated array of items to be purchased.                |
| **fulfillment\_address**    | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address) | Updated fulfillment address.                           |
| **fulfillment\_option\_id** | `string` (optional)                                                                                           | Identifier for the selected fulfillment option.        |

**Example request:**

```json
PUT /checkouts/:id
{
  "items": [
    {
      "id": "item_123",
      "quantity": 3
    },
    {
      "id": "item_456",
      "quantity": 1
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "fulfillment_option_id": "shipping_fast"
}
```

### Response 

The response returns the current state of the checkout from the seller.

| Parameter                   | Type                                                                                                                   | Description                                                                                                                                                     |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id**                      | `string`                                                                                                               | Unique identifier for the Checkout Session. (Required)                                                                                                          |
| **buyer**                   | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)            | Information about the buyer.                                                                                                                                    |
| **payment\_provider**       | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#payment-provider) | Payment provider configuration and supported payment methods.                                                                                                   |
| **status**                  | `string`                                                                                                               | Current status of the checkout process. (Required)

  Possible values: `not_ready_for_payment` | `ready_for_payment` | `completed` | `canceled` | `in_progress` |
| **currency**                | `string`                                                                                                               | Three-letter ISO currency code, in lowercase. (Required)                                                                                                        |
| **line\_items**             | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#line-item)                  | Array of line items in the checkout process. (Required)                                                                                                         |
| **fulfillment\_address**    | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address)          | Address where the order will ship.                                                                                                                              |
| **fulfillment\_options**    | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#fulfillment-option)         | Available shipping and fulfillment options. (Required)                                                                                                          |
| **fulfillment\_option\_id** | `string` (optional)                                                                                                    | ID of the currently selected fulfillment option.                                                                                                                |
| **totals**                  | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#total)                      | Overview of charges and discounts. (Required)                                                                                                                   |
| **messages**                | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#message)                    | Array of messages or notifications related to the checkout process. (Required)                                                                                  |
| **links**                   | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#link)                       | Array of links related to the checkout process. (Required)                                                                                                      |

**Example response:**

```json
{
  "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": 3
      },
      "base_amount": 3000,
      "discount": 0,
      "total": 3000,
      "subtotal": 3000,
      "tax": 0
    },
    {
      "id": "item_456",
      "item": {
        "id": "item_456",
        "quantity": 1
      },
      "base_amount": 500,
      "discount": 0,
      "total": 500,
      "subtotal": 500,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "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": 3500
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 3750
    }
  ],
  "messages": [],
  "links": []
}
```

## Complete a Checkout 

You can complete the checkout process by processing the payment and creating an order.

### Request 

Specify the parameters required for your request.

| Parameter         | Type                                                                                                        | Description                                                       |
| ----------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **id**            | `string`                                                                                                    | Unique identifier for the checkout process. (Required)            |
| **buyer**         | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer) | Information about the buyer.                                      |
| **payment\_data** | `hash` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#payment-data)     | Payment method details for processing the transaction. (Required) |

**Example request:**

```json
POST /checkouts/:id/complete
{
  "payment_data": {
    "token": "spt_123",
    "provider": "stripe",
    "billing_address": {
      "name": "John Doe",
      "line_one": "123 Main St",
      "line_two": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94105"
    }
  }
}
```

### Response 

The response returns the current state of the checkout from the seller.

| Parameter                   | Type                                                                                                                   | Description                                                                                                                                                     |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id**                      | `string`                                                                                                               | Unique identifier for the Checkout Session. (Required)                                                                                                          |
| **buyer**                   | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)            | Information about the buyer.                                                                                                                                    |
| **payment\_provider**       | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#payment-provider) | Payment provider configuration and supported payment methods.                                                                                                   |
| **status**                  | `string`                                                                                                               | Current status of the checkout process. (Required)

  Possible values: `not_ready_for_payment` | `ready_for_payment` | `completed` | `canceled` | `in_progress` |
| **currency**                | `string`                                                                                                               | Three-letter ISO currency code, in lowercase. (Required)                                                                                                        |
| **line\_items**             | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#line-item)                  | Array of line items in the checkout process. (Required)                                                                                                         |
| **fulfillment\_address**    | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address)          | Address where the order will ship.                                                                                                                              |
| **fulfillment\_options**    | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#fulfillment-option)         | Available shipping and fulfillment options. (Required)                                                                                                          |
| **fulfillment\_option\_id** | `string` (optional)                                                                                                    | ID of the currently selected fulfillment option.                                                                                                                |
| **totals**                  | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#total)                      | Overview of charges and discounts. (Required)                                                                                                                   |
| **messages**                | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#message)                    | Array of messages or notifications related to the checkout process. (Required)                                                                                  |
| **links**                   | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#link)                       | Array of links related to the checkout process. (Required)                                                                                                      |

**Example response:**

```json
{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+1234567890"
  },
  "status": "completed",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 3
      },
      "base_amount": 3000,
      "discount": 0,
      "total": 3000,
      "subtotal": 3000,
      "tax": 0
    },
    {
      "id": "item_456",
      "item": {
        "id": "item_456",
        "quantity": 1
      },
      "base_amount": 500,
      "discount": 0,
      "total": 500,
      "subtotal": 500,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "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": 3500
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 3750
    }
  ],
  "messages": [],
  "links": []
}
```

## Cancel a Checkout 

You can cancel an existing Checkout Session if necessary.

### Request 

Specify the parameters required for your request.

| Parameter | Type     | Description                                            |
| --------- | -------- | ------------------------------------------------------ |
| **id**    | `string` | Unique identifier for the checkout process. (Required) |

**Example request:**

```json
POST /checkouts/:id/cancel
{}
```

### Response 

The response returns the current state of the checkout from the seller.

| Parameter                   | Type                                                                                                                   | Description                                                                                                                                                     |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id**                      | `string`                                                                                                               | Unique identifier for the Checkout Session. (Required)                                                                                                          |
| **buyer**                   | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)            | Information about the buyer.                                                                                                                                    |
| **payment\_provider**       | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#payment-provider) | Payment provider configuration and supported payment methods.                                                                                                   |
| **status**                  | `string`                                                                                                               | Current status of the checkout process. (Required)

  Possible values: `not_ready_for_payment` | `ready_for_payment` | `completed` | `canceled` | `in_progress` |
| **currency**                | `string`                                                                                                               | Three-letter ISO currency code, in lowercase. (Required)                                                                                                        |
| **line\_items**             | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#line-item)                  | Array of line items in the checkout process. (Required)                                                                                                         |
| **fulfillment\_address**    | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address)          | Address where the order will ship.                                                                                                                              |
| **fulfillment\_options**    | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#fulfillment-option)         | Available shipping and fulfillment options. (Required)                                                                                                          |
| **fulfillment\_option\_id** | `string` (optional)                                                                                                    | ID of the currently selected fulfillment option.                                                                                                                |
| **totals**                  | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#total)                      | Overview of charges and discounts. (Required)                                                                                                                   |
| **messages**                | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#message)                    | Array of messages or notifications related to the checkout process. (Required)                                                                                  |
| **links**                   | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#link)                       | Array of links related to the checkout process. (Required)                                                                                                      |

**Example response:**

```json
{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+1234567890"
  },
  "status": "canceled",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 3
      },
      "base_amount": 3000,
      "discount": 0,
      "total": 3000,
      "subtotal": 3000,
      "tax": 0
    },
    {
      "id": "item_456",
      "item": {
        "id": "item_456",
        "quantity": 1
      },
      "base_amount": 500,
      "discount": 0,
      "total": 500,
      "subtotal": 500,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "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": 3500
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 3750
    }
  ],
  "messages": [
    {
      "type": "info",
      "content_type": "plain",
      "content": "Checkout cancelled: Customer changed their mind"
    }
  ],
  "links": []
}
```

## Data structures 

This section outlines the data structures involved in the checkout process.

### Buyer 

The buyer is an individual who initiates the purchase.

| Parameter         | Type                | Description                             |
| ----------------- | ------------------- | --------------------------------------- |
| **first\_name**   | `string`            | The first name of the buyer. (Required) |
| **last\_name**    | `string`            | The last name of the buyer. (Required)  |
| **email**         | `string`            | The email of the buyer. **Required**    |
| **phone\_number** | `string` (optional) | The phone number of the buyer.          |

### Item 

The Item is a product or service that the buyer requests to purchase, along with its quantity.

| Parameter    | Type      | Description                                                      |
| ------------ | --------- | ---------------------------------------------------------------- |
| **id**       | `string`  | Unique identifier for the item. (Required)                       |
| **quantity** | `integer` | The requested quantity of the item for this checkout. (Required) |

### LineItem 

The LineItem includes provides about the item added to the checkout, including the amount.

| Parameter        | Type                                                                                            | Description                                      |
| ---------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| **id**           | `string`                                                                                        | Unique identifier for the line item. (Required)  |
| **item**         | `hash` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#item) | The item details. (Required)                     |
| **base\_amount** | `integer`                                                                                       | The base amount of the line item. (Required)     |
| **discount**     | `integer`                                                                                       | The discount amount of the line item. (Required) |
| **total**        | `integer`                                                                                       | The total amount of the line item. (Required)    |
| **subtotal**     | `integer`                                                                                       | The subtotal amount of the line item. (Required) |
| **tax**          | `integer`                                                                                       | The tax amount of the line item. (Required)      |

### Address 

The Address provides the buyer’s shipping or billing address.

| Parameter        | Type                | Description                                                               |
| ---------------- | ------------------- | ------------------------------------------------------------------------- |
| **name**         | `string`            | Name of the person to whom the items are fulfilled. (Required)            |
| **line\_one**    | `string`            | Address line 1 (for example, street, PO Box, or company name). (Required) |
| **line\_two**    | `string` (optional) | Address line 2 (for example, apartment, suite, unit, or building).        |
| **city**         | `string`            | City, district, suburb, town, or village. (Required)                      |
| **state**        | `string`            | State, county, province, or region. (Required)                            |
| **country**      | `string`            | Two-letter country code (ISO 3166-1 alpha-2). (Required)                  |
| **postal\_code** | `string`            | ZIP or postal code. (Required)                                            |

### PaymentData 

The PaymentData provides the buyer’s payment details, including the tokenized value and the payment provider.

| Parameter            | Type                                                                                                          | Description                                                   |
| -------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **token**            | `string`                                                                                                      | The secure reference to a payment credential. (Required)      |
| **provider**         | `string`                                                                                                      | The payment provider that the payment data is for. (Required) |
| **billing\_address** | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address) | Billing address for the payment method.                       |

### Total 

The Total provides a summary of the overall total.

| Parameter         | Type      | Description                                                                                                                                                  |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **type**          | `enum`    | The type of total. (Required)

  Possible values: `items_base_amount` | `items_discount` | `subtotal` | `discount` | `fulfillment` | `tax` | `fee` | `total` |
| **display\_text** | `string`  | The display text for the total. (Required)                                                                                                                   |
| **amount**        | `integer` | The amount of the total. (Required)                                                                                                                          |

### FulfillmentOption 

Fulfillment options are either shipping or digital. See [ShippingFulfillmentOption](https://docs.stripe.com/agentic-commerce/protocol/specification.md#shipping-fulfillment-option) and [DigitalFulfillmentOption](https://docs.stripe.com/agentic-commerce/protocol/specification.md#digital-fulfillment-option) for specific implementations.

### ShippingFulfillmentOption 

The ShippingFulfillmentOption defines the parameters for shipping fulfillment options, including the carrier information and delivery times.

| Parameter                    | Type                | Description                                                                      |
| ---------------------------- | ------------------- | -------------------------------------------------------------------------------- |
| **type**                     | `enum`              | The type of fulfillment option. (Required)

  Possible values: `shipping`        |
| **id**                       | `string`            | Unique identifier for the shipping fulfillment option. (Required)                |
| **title**                    | `string`            | The title of the shipping fulfillment option. (Required)                         |
| **subtitle**                 | `string` (optional) | The subtitle of the shipping fulfillment option.                                 |
| **carrier**                  | `string` (optional) | The carrier of the shipping fulfillment option.                                  |
| **earliest\_delivery\_time** | `string` (optional) | The earliest delivery time of the shipping fulfillment option (ISO 8601 format). |
| **latest\_delivery\_time**   | `string` (optional) | The latest delivery time of the shipping fulfillment option (ISO 8601 format).   |
| **subtotal**                 | `integer`           | The subtotal of the shipping fulfillment option. (Required)                      |
| **tax**                      | `integer`           | The tax of the shipping fulfillment option. (Required)                           |
| **total**                    | `integer`           | The total of the shipping fulfillment option. (Required)                         |

### DigitalFulfillmentOption 

The DigitalFulfillmentOption defines the parameters for digital fulfillment options, including the title and pricing information.

| Parameter    | Type                | Description                                                              |
| ------------ | ------------------- | ------------------------------------------------------------------------ |
| **type**     | `enum`              | The type of fulfillment option. (Required)

  Possible values: `digital` |
| **id**       | `string`            | Unique identifier for the digital fulfillment option. (Required)         |
| **title**    | `string`            | The title of the digital fulfillment option. (Required)                  |
| **subtitle** | `string` (optional) | The subtitle of the digital fulfillment option.                          |
| **subtotal** | `integer`           | The subtotal of the digital fulfillment option. (Required)               |
| **tax**      | `integer`           | The tax of the digital fulfillment option. (Required)                    |
| **total**    | `integer`           | The total of the digital fulfillment option. (Required)                  |

### PaymentProvider 

The PaymentProvider defines the seller’s supported payment provider and available methods.

| Parameter                       | Type     | Description                                                                      |
| ------------------------------- | -------- | -------------------------------------------------------------------------------- |
| **provider**                    | `string` | The seller’s payment provider. (Required)

  Possible values: `stripe`           |
| **supported\_payment\_methods** | `array`  | The payment methods allowed by the seller. (Required)

  Possible values: `card` |

### Message 

Messages are either informational or error messages.

#### InfoMessage 

The InfoMessage represents informational messages, detailing the type and content.

| Parameter         | Type                | Description                                                                             |
| ----------------- | ------------------- | --------------------------------------------------------------------------------------- |
| **type**          | `enum`              | String value representing message type.

  Possible values: `info`                      |
| **param**         | `string` (optional) | RFC 9535 JSONPath to the component of the Checkout Session that the message references. |
| **content\_type** | `enum` (optional)   | The type of content of the message.

  Possible values: `plain` | `markdown`            |
| **content**       | `string`            | The content of the message.                                                             |

#### ErrorMessage 

The ErrorMessage represents error messages, detailing the type and code.

| Parameter         | Type                | Description                                                                                                                                  |
| ----------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **type**          | `enum`              | String value representing message type.

  Possible values: `error`                                                                          |
| **code**          | `enum`              | The code of the error.

  Possible values: `missing` | `invalid` | `out_of_stock` | `payment_declined` | `requires_sign_in` | `requires_3ds` |
| **param**         | `string` (optional) | RFC 9535 JSONPath to the component of the Checkout Session that the message references.                                                      |
| **content\_type** | `enum` (optional)   | The type of content of the message.

  Possible values: `plain` | `markdown`                                                                 |
| **content**       | `string`            | The content of the message.                                                                                                                  |

### Error 

The Error defines the parameters related to errors occurring during the checkout process.

| Parameter   | Type                | Description                                                                                                                                 |
| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **type**    | `enum`              | The type of error. (Required)

  Possible values: `invalid_request` | `request_not_idempotent` | `processing_error` | `service_unavailable` |
| **code**    | `string`            | The implementation-defined error code. (Required)                                                                                           |
| **message** | `string`            | The message of the error. (Required)                                                                                                        |
| **param**   | `string` (optional) | RFC 9535 JSONPath to the component of the Checkout Session that the message references.                                                     |

### Link 

The Link defines the parameters for links related to policies and agreements.

| Parameter | Type     | Description                                                                                                                           |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **type**  | `enum`   | String value representing the type of link. (Required)

  Possible values: `terms_of_use` | `privacy_policy` | `seller_shop_policies` |
| **url**   | `string` | The URL of the link. (Required)                                                                                                       |

### Order 

The Order provides the result of the checkout process and offers details to the buyer for order lookup.

| Parameter                 | Type     | Description                                                                  |
| ------------------------- | -------- | ---------------------------------------------------------------------------- |
| **id**                    | `string` | Unique identifier for the order. (Required)                                  |
| **checkout\_session\_id** | `string` | Reference to the Checkout Session that the order originated from. (Required) |
| **permalink\_url**        | `string` | The permalink URL for the order. (Required)                                  |

### Event 

The Event defines the parameters for events related to order creation and updates.

| Parameter | Type                                                                                                        | Description                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **type**  | `enum`                                                                                                      | The type of event. (Required)

  Possible values: `order_created` | `order_updated` |
| **data**  | `hash` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#order-event-data) | Event data containing order information. (Required)                                 |

### OrderEventData 

The OrderEventData includes data related to order events.

| Parameter                 | Type                                                                                               | Description                                                                                                                                                         |
| ------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **type**                  | `string`                                                                                           | The string value represents the type of event data. For order data, use the value `order`. (Required)                                                               |
| **checkout\_session\_id** | `string`                                                                                           | ID that identifies the Checkout Session that created this order. (Required)                                                                                         |
| **permalink\_url**        | `string`                                                                                           | The URL points to the order. Customers can visit this URL and provide their email address to view order details. (Required)                                         |
| **status**                | `enum`                                                                                             | String representing the latest status of the order. (Required)

  Possible values: `created` | `manual_review` | `confirmed` | `canceled` | `shipped` | `fulfilled` |
| **refunds**               | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#refund) | List of refunds that have been issued for the order. (Required)                                                                                                     |

### Refund 

The Refund defines the parameters for managing refunds associated with completed orders.

| Parameter  | Type      | Description                                                                            |
| ---------- | --------- | -------------------------------------------------------------------------------------- |
| **type**   | `enum`    | The type of refund. (Required)

  Possible values: `store_credit` | `original_payment` |
| **amount** | `integer` | The amount of the refund. (Required)                                                   |