Update a Checkout Session ​
Updates a Checkout Session object.
Related guide: Dynamically update a Checkout Session
Returns ​
Returns a Checkout Session object.
Parameters ​
collected_information(object, optional) Information about the customer collected within the Checkout Session. Can only be set when updatingembeddedorcustomsessions.collected_information.shipping_details(object, optional) The shipping details to apply to this Session.collected_information.shipping_details.address(object, required) The address of the customercollected_information.shipping_details.address.country(string, required) Two-letter country code (ISO 3166-1 alpha-2).collected_information.shipping_details.address.line1(string, required) Address line 1, such as the street, PO Box, or company name.collected_information.shipping_details.address.city(string, optional) City, district, suburb, town, or village.collected_information.shipping_details.address.line2(string, optional) Address line 2, such as the apartment, suite, unit, or building.collected_information.shipping_details.address.postal_code(string, optional) ZIP or postal code.collected_information.shipping_details.address.state(string, optional) State, county, province, or region (ISO 3166-2).
collected_information.shipping_details.name(string, required) The name of customerThe maximum length is 255 characters.
line_items(array of objects, optional) 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
idalong with the new values of the fields to update.To add a new line item, specify one of
priceorprice_dataandquantity.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_quantity(object, optional) When set, provides configuration for this item’s quantity to be adjusted by the customer during Checkout.line_items.adjustable_quantity.enabled(boolean, required) 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.maximum(integer, optional) 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.minimum(integer, optional) The minimum quantity the customer must purchase for the Checkout Session. By default this value is 0.
line_items.id(string, optional) ID of an existing line item.line_items.metadata(object, optional) 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 tometadata.line_items.price(string, required conditionally) The ID of the Price. One ofpriceorprice_datais required when creating a new line item.line_items.price_data(object, required conditionally) Data used to generate a new Price object inline. One ofpriceorprice_datais required when creating a new line item.line_items.price_data.currency(enum, required) Three-letter ISO currency code, in lowercase. Must be a supported currency.line_items.price_data.product(string, required conditionally) The ID of the Product that this Price will belong to. One ofproductorproduct_datais required.line_items.price_data.product_data(object, required conditionally) Data used to generate a new Product object inline. One ofproductorproduct_datais required.line_items.price_data.product_data.name(string, required) The product’s name, meant to be displayable to the customer.line_items.price_data.product_data.description(string, optional) 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.images(array of strings, optional) 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.metadata(object, optional) 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 tometadata.line_items.price_data.product_data.tax_code(string, recommended if calculating taxes) A tax code ID.line_items.price_data.product_data.tax_details(object, recommended if calculating taxes) Tax details for this product, including the tax code and an optional performance location.line_items.price_data.product_data.tax_details.performance_location(string, optional) A tax location ID. Depending on the tax code, this is required, optional, or not supported.line_items.price_data.product_data.tax_details.tax_code(string, optional) A tax code ID.
line_items.price_data.product_data.unit_label(string, optional) 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.recurring(object, optional) The recurring components of a price such asintervalandinterval_count.line_items.price_data.recurring.interval(enum, required) Specifies billing frequency. Eitherday,week,monthoryear. Possible enum values:daymonthweekyear
line_items.price_data.recurring.interval_count(integer, optional) The number of intervals between subscription billings. For example,interval=monthandinterval_count=3bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks).
line_items.price_data.tax_behavior(enum, recommended 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 ofinclusive,exclusive, orunspecified. Once specified as eitherinclusiveorexclusive, it cannot be changed. Possible enum values:exclusiveinclusiveunspecified
line_items.price_data.unit_amount(integer, required conditionally) A non-negative integer in the smallest currency unit representing how much to charge. One ofunit_amountorunit_amount_decimalis required.line_items.price_data.unit_amount_decimal(string, required conditionally) Same asunit_amount, but accepts a decimal value in the smallest currency unit with at most 12 decimal places. Only one ofunit_amountandunit_amount_decimalcan be set.
line_items.quantity(integer, required conditionally) The quantity of the line item being purchased. Quantity should not be defined whenrecurring.usage_type=metered.line_items.tax_rates(array of strings, optional) The tax rates which apply to this line item.
metadata(object, optional) 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 tometadata.shipping_options(array of objects, optional) The shipping rate options to apply to this Session. Up to a maximum of 5.shipping_options.shipping_rate(string, required unless shipping_rate_data is provided) The ID of the Shipping Rate to use for this shipping option.shipping_options.shipping_rate_data(object, required unless shipping_rate is provided) Parameters to be passed to Shipping Rate creation for this shipping option.shipping_options.shipping_rate_data.display_name(string, required) 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_estimate(object, optional) 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.maximum(object, optional) The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.shipping_options.shipping_rate_data.delivery_estimate.maximum.unit(enum, required) A unit of time. Possible enum values:business_dayThe delivery estimate is in business days.dayThe delivery estimate is in days.hourThe delivery estimate is in hours.monthThe delivery estimate is in months.weekThe delivery estimate is in weeks.
shipping_options.shipping_rate_data.delivery_estimate.maximum.value(integer, required) Must be greater than 0.
shipping_options.shipping_rate_data.delivery_estimate.minimum(object, optional) The lower bound of the estimated range. If empty, represents no lower bound.shipping_options.shipping_rate_data.delivery_estimate.minimum.unit(enum, required) A unit of time. Possible enum values:business_dayThe delivery estimate is in business days.dayThe delivery estimate is in days.hourThe delivery estimate is in hours.monthThe delivery estimate is in months.weekThe delivery estimate is in weeks.
shipping_options.shipping_rate_data.delivery_estimate.minimum.value(integer, required) Must be greater than 0.
shipping_options.shipping_rate_data.fixed_amount(object, optional) Describes a fixed amount to charge for shipping. Must be present if type isfixed_amount.shipping_options.shipping_rate_data.fixed_amount.amount(integer, required) A non-negative integer in cents representing how much to charge.shipping_options.shipping_rate_data.fixed_amount.currency(enum, required) Three-letter ISO currency code, in lowercase. Must be a supported currency.shipping_options.shipping_rate_data.fixed_amount.currency_options(object, optional) 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>.amount(integer, required) A non-negative integer in cents representing how much to charge.shipping_options.shipping_rate_data.fixed_amount.currency_options.<currency>.tax_behavior(enum, recommended if calculating taxes) Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One ofinclusive,exclusive, orunspecified. Possible enum values:exclusiveinclusiveunspecified
shipping_options.shipping_rate_data.metadata(object, optional) 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 tometadata.shipping_options.shipping_rate_data.tax_behavior(enum, recommended if calculating taxes) Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One ofinclusive,exclusive, orunspecified. Possible enum values:exclusiveinclusiveunspecified
shipping_options.shipping_rate_data.tax_code(string, recommended if calculating taxes) A tax code ID. The Shipping tax code istxcd_92010001.shipping_options.shipping_rate_data.type(enum, required) The type of calculation to use on the shipping rate. Possible enum values:fixed_amountThe shipping rate is a fixed amount.
curl
curl https://api.stripe.com/v1/checkout/sessions/cs_test_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u \
-u "<<YOUR_SECRET_KEY>>" \
-d "metadata[order_id]=6735"Response ​
json
{
"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"
}