> ## 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.

# Cancel Checkout

> Cancel an existing checkout session

<Note>
  This endpoint cancels an active checkout session. Once canceled, the checkout cannot be completed or updated. This is useful when a customer abandons their cart or decides not to proceed with the purchase.
</Note>

## Authentication

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

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

## Path Parameters

<ParamField path="id" type="string" required>
  Unique identifier for the checkout session
</ParamField>

## Request Body

<ParamField body="reason" type="string">
  Optional reason for canceling the checkout (e.g., "customer\_requested", "timeout", "inventory\_unavailable")
</ParamField>

<ParamField body="message" type="string">
  Optional custom message about the cancellation
</ParamField>

### Response

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

<ResponseField name="status" type="string">
  Status will be `canceled` after successful cancellation
</ResponseField>

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

<ResponseField name="line_items" type="array">
  Line items from the canceled checkout
</ResponseField>

<ResponseField name="totals" type="array">
  Final totals before cancellation
</ResponseField>

<ResponseField name="messages" type="array">
  Array including cancellation message
</ResponseField>

<ResponseField name="canceled_at" type="string">
  ISO 8601 timestamp of when the checkout was canceled
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.stateset.com/v1/checkouts/checkout_abc123/cancel \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "reason": "customer_requested",
      "message": "Customer changed their mind"
    }'
  ```

  ```javascript Node.js theme={null}
  const checkout = await stateset.checkouts.cancel('checkout_abc123', {
    reason: "customer_requested",
    message: "Customer changed their mind"
  });
  ```

  ```python Python theme={null}
  checkout = stateset.checkouts.cancel(
      'checkout_abc123',
      reason="customer_requested",
      message="Customer changed their mind"
  )
  ```
</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"
    },
    "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": [],
    "canceled_at": "2024-09-30T14:30:00Z"
  }
  ```

  ```json Error Response - Already Completed theme={null}
  {
    "success": false,
    "error": {
      "type": "invalid_request",
      "code": "INVALID_STATUS",
      "message": "Cannot cancel a checkout that has already been completed",
      "param": "status"
    }
  }
  ```

  ```json Error Response - Not Found theme={null}
  {
    "success": false,
    "error": {
      "type": "invalid_request",
      "code": "RESOURCE_NOT_FOUND",
      "message": "Checkout session not found",
      "param": "id"
    }
  }
  ```
</ResponseExample>