Update Checkout Session | PaymentKit

{
  "id": "cs_dev_x7k9m2n4p8q1",
  "account_id": "acc_dev_x7k9m2n4p8q1",
  "secure_token": "tok_abc123xyz789",
  "expires_in_hours": 24,
  "completed": false,
  "state": "open",
  "is_expired": false,
  "success_url": "https://example.com/success",
  "return_url": "https://example.com/return",
  "card_tokenization_mode": "direct",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "customer_id": "user_dev_x7k9m2n4p8q1",
  "customer_email": "taylor@example.com",
  "line_items": [
    {
      "id": "csli_dev_x7k9m2n4p8q1",
      "product_id": "product_dev_x7k9m2n4",
      "price_id": "price_dev_x7k9m2n4",
      "quantity": 1,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "description": "Premium subscription plan"
    }
  ],
  "coupon_id": "coupon_dev_x7k9m2n4",
  "promotion_code": "SAVE20",
  "card_checkout_settings": {
    "three_ds_mode": "prefer_non_3ds"
  },
  "cascade_status": {
    "total_tiers": 3,
    "tier_amounts": [
      10000,
      8000,
      5000
    ]
  },
  "cascade_tiers": [
    {
      "line_items": [
        {
          "price_id": "price_dev_x7k9m2n4",
          "quantity": 1,
          "description": "Fallback subscription plan"
        }
      ],
      "processor_route_id": "proute_dev_x7k9m2n4",
      "inline_route": {
        "processors": [
          {
            "processor_id": "proc_dev_stripe"
          }
        ],
        "name": "string",
        "description": "string"
      }
    }
  ],
  "processor_route_id": "proute_dev_x7k9m2n4",
  "inline_route": {
    "processors": [
      {
        "processor_id": "proc_dev_stripe"
      }
    ],
    "name": "string",
    "description": "string"
  },
  "setup_preferences": {},
  "custom_fields": {},
  "params_for_sub": {
    "custom_fields": {}
  },
  "statement_descriptor_suffix": "string"
}

Update a checkout session.

Currently supports updating:

processor_route_id: Override the processor route for card checkout
params_for_sub: Parameters to pass to the subscription created from this session
statement_descriptor_suffix: Session-level descriptor suffix override; send "" or null to clear it

Only works on open (non-completed, non-expired) sessions. Works for both User and API Key authentication.

Update a checkout session. Currently supports updating: - processor_route_id: Override the processor route for card checkout - params_for_sub: Parameters to pass to the subscription created from this session - statement_descriptor_suffix: Session-level descriptor suffix override; send "" or null to clear it Only works on open (non-completed, non-expired) sessions. Works for both User and API Key authentication.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

external_idstringRequired

account_idstringRequired

Request

This endpoint expects an object.

processor_route_idstring or nullOptional

ID of a processor route to use for card checkout. A processor route contains an ordered list of processors tried sequentially as a fallback chain.

inline_routeobject or nullOptional

Define processors directly on this session instead of referencing a predefined route. Setting this automatically clears processor_route_id. Mutually exclusive with processor_route_id — set one or the other, not both. Set to null to remove the inline route.

params_for_subobject or nullOptional

Parameters to pass to the subscription when created from this checkout session. Set to null to clear.

statement_descriptor_suffixstring or nullOptional

Statement descriptor suffix for this checkout session. Send an empty string ("") or null to clear it; omit the field to leave it unchanged. A value too long for the account prefix is trimmed to fit (the trimmed value is returned); an invalid one is rejected with 422.

Response

Successful Response

idstring

Unique checkout session identifier

account_idstring

Account identifier

secure_tokenstring

Secure token for accessing the checkout session

expires_in_hoursinteger

Number of hours until the checkout session expires

completedboolean

Whether the checkout session has been completed

stateenum

Computed state of the checkout session

is_expiredboolean

Whether the checkout session has expired

success_urlstring

URL to redirect to on success

return_urlstring

URL to return to on cancellation

card_tokenization_modeenum

Card tokenization mode: ‘direct’ (KMS encryption) or ‘vgs’ (VGS Collect + proxy)

created_atdatetime

When the checkout session was created

updated_atdatetime

When the checkout session was last updated

customer_idstring or nullOptional

Customer identifier

customer_emailstring or nullOptional

Customer email address

line_itemslist of objectsOptional

List of line items in the checkout session

coupon_idstring or nullOptional

ID of the coupon applied to this checkout session

promotion_codestring or nullOptional

Promotion code used to apply the coupon

card_checkout_settingsobjectOptional

Settings for card checkout behavior (parallel setup, 3DS mode)

cascade_statusobject or nullOptional

Cascade pricing status (None if no cascade configured)

cascade_tierslist of objects or nullOptional

Full cascade tier details including processor routes (None if no cascade configured)

processor_route_idstring or nullOptional

ID of the processor route used for card checkout. A processor route contains an ordered list of processors tried sequentially as a fallback chain. This is a single route ID, not an array — to use multiple processors, define them within the route itself.

inline_routeobject or nullOptional

Inline processor route defined directly on this session. Contains the ordered list of processors to try as a fallback chain. Null if a predefined processor_route_id is used instead, or if no route is configured.

modeanyOptional

Checkout session mode

setup_preferencesmap from strings to any or nullOptional

Preferences for payment method setup

custom_fieldsmap from strings to any or nullOptional

Custom field values. Only included when expand=custom_fields is specified.

params_for_subobject or nullOptional

Parameters to pass to the subscription when created from this checkout session.

statement_descriptor_suffixstring or nullOptional

Statement descriptor suffix for this checkout session. Applied to the charge made from this session and copied onto any subscription created from it, so renewals inherit it. Null when not set.

Errors

422

Unprocessable Entity Error

$	curl -X PATCH https://app.paymentkit.com/api/account_id/checkout-sessions/external_id \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{}'