Update Checkout Session

Update an existing checkout session by modifying items, shipping address, or fulfillment options

PUT /v1/checkouts/:id

cURL

curl -X PUT https://api.stateset.com/v1/checkouts/checkout_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

Success Response

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

This endpoint updates an existing Checkout Session. You can modify line items, buyer information, shipping address, or select different fulfillment options. The response will include recalculated totals.

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

items · array

Updated array of items to purchase

Show Item object properties

id · string · required

Unique identifier for the item

quantity · integer · required

Updated quantity of the item

buyer · object

Updated buyer information

Show Buyer properties

first_name · string

First name of the buyer

last_name · string

Last name of the buyer

email · string

Email address of the buyer

phone_number · string

Phone number of the buyer

fulfillment_address · object

Updated fulfillment address

Show Address properties

name · string

Name of the person receiving the items

line_one · string

Street address line 1

line_two · string

Street address line 2

city · string

City name

state · string

State or province code

country · string

ISO 3166-1 alpha-2 country code

postal_code · string

Postal or ZIP code

fulfillment_option_id · string

Identifier for the selected fulfillment option

Response

Returns the updated checkout session with recalculated totals.

cURL

curl -X PUT https://api.stateset.com/v1/checkouts/checkout_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

Success Response

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