Update a Checkout Session

​

Updates mutable fields on an existing Checkout Session. This endpoint currently supports selecting one of the session's existing shipping rates while the session is still open.

Use this endpoint when your checkout page lets the customer choose a shipping option after the session has been created. Paypercut applies the selected shipping rate to the Checkout Session and updates the related Payment Intent amount before confirmation.

Checkout Sessions can no longer be updated after payment confirmation has started. To retry a completed, expired, or already-confirming checkout, create a new Checkout Session.

Related guides: Checkout Experience and Checkout Sessions API

Path Parameters
  • id
    Type: string
    max length:  
    200
    required
Headers
  • Idempotency-Key
    Type: string
    max length:  
    255     Pattern: ^[a-zA-Z0-9:_\-.]+$

    Provide a unique, stable key per operation so retries don't create duplicates. Allowed: letters, digits, colon, dash, underscore, dot. Max 255 characters.

Body·
required
application/json

Request parameters for updating a Checkout Session.

  • shipping_rate
    Type: string
    required

    ID of one of the Checkout Session's existing shipping rates to apply as the selected shipping cost.

    The session must be open. Selecting a shipping rate updates the Checkout Session amount and the related Payment Intent amount before confirmation.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v1/checkouts/{id}
curl 'https://api.paypercut.io/v1/checkouts/{id}' \
  --request POST \
  --header 'Idempotency-Key: order:12345:pi:create' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "shipping_rate": "shr_standard"
}'

{
  "id": "21210021c2855007efa2d657018",
  "currency": {
    "iso": "usd",
    "scale": 2
  },
  "description": null,
  "mode": "payment",
  "ui_mode": "hosted",
  "amount_total": 100,
  "amount_subtotal": 100,
  "total_details": {
    "amount_discount": 100,
    "amount_shipping": 100,
    "amount_tax": 100
  },
  "shipping_options": [
    {
      "shipping_rate": {
        "id": "shr_standard",
        "display_name": "Standard shipping",
        "type": "fixed_amount",
        "fixed_amount": {
          "amount": 100,
          "currency": "EUR"
        },
        "delivery_estimate": {
          "minimum": {
            "unit": "business_day",
            "value": 3
          },
          "maximum": {
            "unit": "business_day",
            "value": 3
          }
        },
        "tax_behavior": "unspecified",
        "tax_code": null,
        "metadata": {
          "additionalProperty": "string"
        },
        "active": true
      }
    }
  ],
  "shipping_cost": {
    "shipping_rate": "shr_standard",
    "amount_subtotal": 100,
    "amount_tax": 100,
    "amount_total": 100,
    "currency": {
      "iso": "usd",
      "scale": 2
    }
  },
  "url": "https://www.example.com",
  "cancel_url": null,
  "success_url": null,
  "return_url": null,
  "payment_method_types": [
    "string"
  ],
  "submit_type": "auto",
  "wallet_options": {
    "apple_pay": {
      "display": "auto"
    },
    "google_pay": {
      "display": "auto"
    }
  },
  "client_reference_id": null,
  "client_customer_id": null,
  "expires_at": null,
  "line_items": [
    {
      "quantity": 2,
      "price": "01K755J9SV2364REVHB915Z2FW",
      "price_data": {
        "active": true,
        "billing_scheme": "per_unit",
        "created": 1,
        "currency": "string",
        "livemode": true,
        "lookup_key": null,
        "product": "01K755J9SV2364REVHB915Z2FW",
        "product_data": {
          "active": true,
          "name": "string",
          "description": "string",
          "unit_label": "string",
          "id": "string"
        },
        "recurring": {
          "interval": "day",
          "interval_count": 1,
          "meter": null,
          "usage_type": "licensed"
        },
        "type": "one_time",
        "unit_amount": null,
        "unit_amount_decimal": null,
        "id": "string"
      },
      "metadata": {
        "additionalProperty": "string"
      }
    }
  ],
  "saved_payment_method_options": {
    "payment_method_save": "disabled"
  },
  "metadata": {
    "additionalProperty": "string"
  },
  "after_completion": {
    "type": "redirect",
    "redirect": {
      "url": "https://example.com"
    },
    "hosted": {
      "custom_message": "string"
    }
  },
  "locale": null,
  "customer": "01K755J9SV2364REVHB915Z2FW",
  "customer_email": null,
  "customer_creation": "always",
  "payment_intent": "01K755J9SY55CS04SQ3JX1NX36",
  "setup_intent": "01K755J9SY55CS04SQ3JX1NX36",
  "payment_link": "01K755J9SV2364REVHB915Z2FW",
  "payment_status": "no_payment_required",
  "status": "complete",
  "next_action": {
    "redirect_to_url": {
      "return_url": null,
      "url": null
    },
    "type": "string",
    "three_d_secure": {
      "flow": "frictionless",
      "status_url": "https://api.yourco.com/v1/payment_intents/pi_123",
      "return_url": null,
      "message": {
        "allowed_origins": [
          "https://merchant.example.com"
        ]
      },
      "hint": {
        "scheme": "visa",
        "version": "2.2.0"
      },
      "idempotency_key": "string"
    }
  },
  "livemode": true,
  "billing_address_collection": "auto"
}

Checkout Session updated successfully.