Add shipping

Learn to use shipping rates and collect shipping addresses with Checkout.

Create a shipping rate

In the Shipping rates section of the Dashboard, add a shipping rate by clicking the New button. Enter an amount, an optional description (e.g., Ground shipping), and an optional estimated shipping time.

Only Checkout with payment mode supports shipping rates. If you want to use shipping rates with subscription mode or create shipping rates with the API, reach out to us.

Shipping address collection

You can collect a customer’s shipping address in Checkout by setting shipping_address_collection when creating 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, it saves the collected shipping address to the Checkout Session object on the shipping property and includes it in the payload of the checkout.session.completed webhook. Additionally, shipping information appears in the Checkout summary section of your payments detail page in Dashboard.

Create a Checkout session with a shipping rate

You can only pass a single shipping rate to the Checkout session at this time.

Create a Checkout session and include the ID of your desired ShippingRate in the shipping_rates parameter. You can get the ID of the rate from the Dashboard. Then pass the shipping_address_collection parameter described in the previous section.

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

require 'json'
require 'sinatra'

post '/create-checkout-session' do
  session = Stripe::Checkout::Session.create({
    payment_method_types: ['card'],
    shipping_rates: ["shr_123456789"],
    shipping_address_collection: {
      allowed_countries: ['US', 'CA'],
    },
    line_items: [{
      price_data: {
        currency: 'usd',
        product_data: {
          name: 'T-shirt',
        },
        unit_amount: 2000,
      },
      quantity: 1,
    }],
    mode: 'payment',
    success_url: 'https://example.com/success',
    cancel_url: 'https://example.com/cancel',
  })

  { id: session.id }.to_json
end

Handling completed transactions

After the payment completes, you can retrieve the shipping amount in the amount_shipping property in the total_details of the completed Checkout session. 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 amount_shipping property:

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

require 'sinatra'

# You can find your endpoint's secret in your webhook settings
endpoint_secret = 'whsec_...'

post '/webhook' do
  event = nil

  # Verify webhook signature and extract the event
  # See https://stripe.com/docs/webhooks/signatures for more information.
  begin
    sig_header = request.env['HTTP_STRIPE_SIGNATURE']
    payload = request.body.read
    event = Stripe::Webhook.construct_event(payload, sig_header, endpoint_secret)
  rescue JSON::ParserError => e
    # Invalid payload
    return status 400
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    return status 400
  end

  if event['type'] == 'checkout.session.completed'
    checkout_session = event['data']['object']

    fulfill_order(checkout_session)
  end

  status 200
end

def fulfill_order(checkout_session)
  amount_shipping = checkout_session.total_details.amount_shipping

  # TODO: Remove error and implement...
  raise NotImplementedError.new(<<~MSG)
    Given the Checkout Session "#{checkout_session.id}" load your internal order from the database then implement your own fulfillment logic.
  MSG
end