Shipping rates let you display various shipping options—like standard, express, and overnight—with more accurate delivery estimates. This guide explains how to set shipping rates with Stripe Checkout, an integration that requires some code.
To charge for shipping based on the customer’s address, you can collect shipping address and write custom code to calculate the shipping rate.
Shipping address collection
2022-08-01 API version changed several shipping properties on the Checkout Session resource. Responses are different on earlier versions. See the API changelog for more details.
You can collect a customer’s shipping address in Checkout by setting
shipping_address_collection when you create a Checkout session. You must also specify which countries to allow shipping to by configuring the
allowed_countries property with an array of two-letter ISO country codes. These countries appear in the Country dropdown in the Shipping Address form on Checkout.
When the customer completes the session, the Checkout Session object saves the collected shipping address on the
shipping_details property and includes it in the payload of the
checkout.session.completed webhook. Additionally, shipping information appears in the Checkout summary section of your payment details page in the Dashboard.
Create a Checkout session with shipping options
Only Checkout with
payment mode supports shipping options.
Create a Checkout session, and define the shipping rates you want to offer in the
shipping_options parameter. You can customize each shipping option with the
|The type of calculation to used on the shipping rate. Can only be |
|How much to charge, in cents. Set it to |
|Which currency to charge in (for example, |
|The name of the shipping rate, to display to the customer.|
|An object describing the estimated delivery time for this shipping rate option. API reference.|
This example code snippet adds two shipping options to the Checkout session:
- Free shipping, with an estimated delivery of 5-7 business days.
- Next day air, at a cost of 15.00 USD, with an estimated delivery of exactly 1 business day.
Customers can select between these two options at checkout time.
The first option in the
shipping_options array is pre-selected for the customer when they land on the checkout page.
Your customers see a shipping selector on the checkout page:
You can configure shipping rates using a number of delivery estimate combinations. The following table contains some examples of plain English delivery estimates, and their corresponding
|1 business day|
|At least 2 business days|
|3 to 7 days|
|4 to 8 hours|
|4 hours to 2 business days|
Handling completed transactions
After the payment completes, you can retrieve the shipping amount in the
amount_total attribute in the
shipping_cost of the completed Checkout session. You can also retrieve the selected shipping rate using the
shipping_rate attribute in
See the Fulfillment guide to learn how to create an event handler to handle completed Checkout sessions.
To test your event handler, install the Stripe CLI and use
stripe listen --forward-to localhost:4242/webhook to forward events to your local server.
As soon as you have a handler, you can access the