Cancel Checkout

Cancel an existing checkout session

POST /v1/checkouts/:id/cancel

cURL

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"
  }'

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

checkout = stateset.checkouts.cancel(
    'checkout_abc123',
    reason="customer_requested",
    message="Customer changed their mind"
)

Success Response

{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "phone_number": "[phone]"
  },
  "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"
}

{
  "success": false,
  "error": {
    "type": "invalid_request",
    "code": "INVALID_STATUS",
    "message": "Cannot cancel a checkout that has already been completed",
    "param": "status"
  }
}

{
  "success": false,
  "error": {
    "type": "invalid_request",
    "code": "RESOURCE_NOT_FOUND",
    "message": "Checkout session not found",
    "param": "id"
  }
}

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.

Authentication

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

Authorization: Bearer YOUR_API_KEY

Path Parameters

id · string · required

Unique identifier for the checkout session

Request Body

reason · string

Optional reason for canceling the checkout (e.g., “customer_requested”, “timeout”, “inventory_unavailable”)

message · string

Optional custom message about the cancellation

Response

id · string

Unique identifier for the Checkout Session

status · string

Status will be canceled after successful cancellation

buyer · object

Information about the buyer

line_items · array

Line items from the canceled checkout

totals · array

Final totals before cancellation

messages · array

Array including cancellation message

canceled_at · string

ISO 8601 timestamp of when the checkout was canceled

cURL

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"
  }'

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

checkout = stateset.checkouts.cancel(
    'checkout_abc123',
    reason="customer_requested",
    message="Customer changed their mind"
)

Success Response

{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "phone_number": "[phone]"
  },
  "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"
}

{
  "success": false,
  "error": {
    "type": "invalid_request",
    "code": "INVALID_STATUS",
    "message": "Cannot cancel a checkout that has already been completed",
    "param": "status"
  }
}

{
  "success": false,
  "error": {
    "type": "invalid_request",
    "code": "RESOURCE_NOT_FOUND",
    "message": "Checkout session not found",
    "param": "id"
  }
}