Core Resources
Payment Methods
Money Management
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Update a Checkout Session 

Checkout
Checkout Sessions
Update a Checkout Session

Updates a Checkout Session object.

Related guide: Dynamically update Checkout

Parameters

  • line_itemsarray of objects

    A list of items the customer is purchasing.

    When updating line items, you must retransmit the entire array of line items.

    To retain an existing line item, specify its id.

    To update an existing line item, specify its id along with the new values of the fields to update.

    To add a new line item, specify one of price or price_data and quantity.

    To remove an existing line item, omit the line item’s ID from the retransmitted array.

    To reorder a line item, specify it at the desired position in the retransmitted array.

    • line_items.adjustable_quantityobject

      When set, provides configuration for this item’s quantity to be adjusted by the customer during Checkout.

      • line_items.adjustable_quantity.enabledbooleanRequired

        Set to true if the quantity can be adjusted to any positive integer. Setting to false will remove any previously specified constraints on quantity.

      • line_items.adjustable_quantity.maximuminteger

        The maximum quantity the customer can purchase for the Checkout Session. By default this value is 99. You can specify a value up to 999999.

      • line_items.adjustable_quantity.minimuminteger

        The minimum quantity the customer must purchase for the Checkout Session. By default this value is 0.

    • line_items.idstring

      ID of an existing line item.

    • line_items.metadataobject

      Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

    • line_items.pricestringRequired conditionally

      The ID of the Price. One of price or price_data is required when creating a new line item.

    • line_items.price_dataobjectRequired conditionally

      Data used to generate a new Price object inline. One of price or price_data is required when creating a new line item.

      • line_items.price_data.currencyenumRequired

        Three-letter ISO currency code, in lowercase. Must be a supported currency.

      • line_items.price_data.productstringRequired conditionally

        The ID of the Product that this Price will belong to. One of product or product_data is required.

      • line_items.price_data.product_dataobjectRequired conditionally

        Data used to generate a new Product object inline. One of product or product_data is required.

        • line_items.price_data.product_data.namestringRequired

          The product’s name, meant to be displayable to the customer.

        • line_items.price_data.product_data.descriptionstring

          The product’s description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes.

        • line_items.price_data.product_data.imagesarray of strings

          A list of up to 8 URLs of images for this product, meant to be displayable to the customer.

        • line_items.price_data.product_data.metadataobject

          Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

        • line_items.price_data.product_data.tax_codestringRecommended if calculating taxes

          A tax code ID.

        • line_items.price_data.product_data.unit_labelstring

          A label that represents units of this product. When set, this will be included in customers’ receipts, invoices, Checkout, and the customer portal.

          The maximum length is 12 characters.

      • line_items.price_data.recurringobject

        The recurring components of a price such as interval and interval_count.

        • line_items.price_data.recurring.intervalenumRequired

          Specifies billing frequency. Either day, week, month or year.

          Possible enum values
          day
          month
          week
          year

        • line_items.price_data.recurring.interval_countinteger

          The number of intervals between subscription billings. For example, interval=month and interval_count=3 bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks).

      • line_items.price_data.tax_behaviorenumRecommended if calculating taxes

        Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.

        Possible enum values
        exclusive
        inclusive
        unspecified

      • line_items.price_data.unit_amountintegerRequired conditionally

        A non-negative integer in cents representing how much to charge. One of unit_amount or unit_amount_decimal is required.

      • line_items.price_data.unit_amount_decimalstringRequired conditionally

        Same as unit_amount, but accepts a decimal value in cents with at most 12 decimal places. Only one of unit_amount and unit_amount_decimal can be set.

    • line_items.quantityintegerRequired conditionally

      The quantity of the line item being purchased. Quantity should not be defined when recurring.usage_type=metered.

    • line_items.tax_ratesarray of strings

      The tax rates which apply to this line item.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

More parameters

  • collected_informationobject

    Information about the customer collected within the Checkout Session. Can only be set when updating embedded or custom sessions.

    • collected_information.shipping_detailsobject

      The shipping details to apply to this Session.

      • collected_information.shipping_details.addressobjectRequired

        The address of the customer

        • collected_information.shipping_details.address.countrystringRequired

          Two-letter country code (ISO 3166-1 alpha-2).

        • collected_information.shipping_details.address.line1stringRequired

          Address line 1, such as the street, PO Box, or company name.

        • collected_information.shipping_details.address.citystring

          City, district, suburb, town, or village.

        • collected_information.shipping_details.address.line2string

          Address line 2, such as the apartment, suite, unit, or building.

        • collected_information.shipping_details.address.postal_codestring

          ZIP or postal code.

        • collected_information.shipping_details.address.statestring

          State, county, province, or region (ISO 3166-2).

      • collected_information.shipping_details.namestringRequired

        The name of customer

        The maximum length is 255 characters.

  • shipping_optionsarray of objects

    The shipping rate options to apply to this Session. Up to a maximum of 5.

    • shipping_options.shipping_ratestringRequired unless shipping_rate_data is provided

      The ID of the Shipping Rate to use for this shipping option.

    • shipping_options.shipping_rate_dataobjectRequired unless shipping_rate is provided

      Parameters to be passed to Shipping Rate creation for this shipping option.

      • shipping_options.shipping_rate_data.display_namestringRequired

        The name of the shipping rate, meant to be displayable to the customer. This will appear on CheckoutSessions.

        The maximum length is 100 characters.

      • shipping_options.shipping_rate_data.delivery_estimateobject

        The estimated range for how long shipping will take, meant to be displayable to the customer. This will appear on CheckoutSessions.

        • shipping_options.shipping_rate_data.delivery_estimate.maximumobject

          The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.

          • shipping_options.shipping_rate_data.delivery_estimate.maximum.unitenumRequired

            A unit of time.

            Possible enum values
            business_day

            The delivery estimate is in business days.

            day

            The delivery estimate is in days.

            hour

            The delivery estimate is in hours.

            month

            The delivery estimate is in months.

            week

            The delivery estimate is in weeks.

          • shipping_options.shipping_rate_data.delivery_estimate.maximum.valueintegerRequired

            Must be greater than 0.

        • shipping_options.shipping_rate_data.delivery_estimate.minimumobject

          The lower bound of the estimated range. If empty, represents no lower bound.

          • shipping_options.shipping_rate_data.delivery_estimate.minimum.unitenumRequired

            A unit of time.

            Possible enum values
            business_day

            The delivery estimate is in business days.

            day

            The delivery estimate is in days.

            hour

            The delivery estimate is in hours.

            month

            The delivery estimate is in months.

            week

            The delivery estimate is in weeks.

          • shipping_options.shipping_rate_data.delivery_estimate.minimum.valueintegerRequired

            Must be greater than 0.

      • shipping_options.shipping_rate_data.fixed_amountobject

        Describes a fixed amount to charge for shipping. Must be present if type is fixed_amount.

        • shipping_options.shipping_rate_data.fixed_amount.amountintegerRequired

          A non-negative integer in cents representing how much to charge.

        • shipping_options.shipping_rate_data.fixed_amount.currencyenumRequired

          Three-letter ISO currency code, in lowercase. Must be a supported currency.

        • shipping_options.shipping_rate_data.fixed_amount.currency_optionsobject

          Shipping rates defined in each available currency option. Each key must be a three-letter ISO currency code and a supported currency.

          • shipping_options.shipping_rate_data.fixed_amount.currency_options.<currency>.amountintegerRequired

            A non-negative integer in cents representing how much to charge.

          • shipping_options.shipping_rate_data.fixed_amount.currency_options.<currency>.tax_behaviorenumRecommended if calculating taxes

            Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified.

            Possible enum values
            exclusive
            inclusive
            unspecified

      • shipping_options.shipping_rate_data.metadataobject

        Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

      • shipping_options.shipping_rate_data.tax_behaviorenumRecommended if calculating taxes

        Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified.

        Possible enum values
        exclusive
        inclusive
        unspecified

      • shipping_options.shipping_rate_data.tax_codestringRecommended if calculating taxes

        A tax code ID. The Shipping tax code is txcd_92010001.

      • shipping_options.shipping_rate_data.typeenumRequired

        The type of calculation to use on the shipping rate.

        Possible enum values
        fixed_amount

        The shipping rate is a fixed amount.

Returns

Returns a Checkout Session object.

POST /v1/checkout/sessions/:id
curl https://api.stripe.com/v1/checkout/sessions/cs_test_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Version: 2025-12-15.preview" \
  -d "metadata[order_id]"=6735
Response
{
  "id": "cs_test_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u",
  "object": "checkout.session",
  "after_expiration": null,
  "allow_promotion_codes": null,
  "amount_subtotal": 2198,
  "amount_total": 2198,
  "automatic_tax": {
    "enabled": false,
    "liability": null,
    "status": null
  },
  "billing_address_collection": null,
  "cancel_url": null,
  "client_reference_id": null,
  "consent": null,
  "consent_collection": null,
  "created": 1679600215,
  "currency": "usd",
  "custom_fields": [],
  "custom_text": {
    "shipping_address": null,
    "submit": null
  },
  "customer": null,
  "customer_creation": "if_required",
  "customer_details": null,
  "customer_email": null,
  "expires_at": 1679686615,
  "invoice": null,
  "invoice_creation": {
    "enabled": false,
    "invoice_data": {
      "account_tax_ids": null,
      "custom_fields": null,
      "description": null,
      "footer": null,
      "issuer": null,
      "metadata": {},
      "rendering_options": null
    }
  },
  "livemode": false,
  "locale": null,
  "metadata": {
    "order_id": "6735"
  },
  "mode": "payment",
  "payment_intent": null,
  "payment_link": null,
  "payment_method_collection": "always",
  "payment_method_options": {},
  "payment_method_types": [
    "card"
  ],
  "payment_status": "unpaid",
  "phone_number_collection": {
    "enabled": false
  },
  "recovered_from": null,
  "setup_intent": null,
  "shipping_address_collection": null,
  "shipping_cost": null,
  "shipping_details": null,
  "shipping_options": [],
  "status": "open",
  "submit_type": null,
  "subscription": null,
  "success_url": "https://example.com/success",
  "total_details": {
    "amount_discount": 0,
    "amount_shipping": 0,
    "amount_tax": 0
  },
  "url": "https://checkout.stripe.com/c/pay/cs_test_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u#fidkdWxOYHwnPyd1blpxYHZxWjA0SDdPUW5JbmFMck1wMmx9N2BLZjFEfGRUNWhqTmJ%2FM2F8bUA2SDRySkFdUV81T1BSV0YxcWJcTUJcYW5rSzN3dzBLPUE0TzRKTTxzNFBjPWZEX1NKSkxpNTVjRjN8VHE0YicpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl"
}