Automated Shipping Calculations

    Use a shipping provider to automatically calculate shipping rates on your Stripe orders.

    Calculating shipping rates on your orders often means keeping several systems in sync or charging a flat-rate amount that either over- or under-charges your customer. If you already have your products represented in Stripe, we can help you calculate accurate shipping rates from a number of carriers without doing any additional work. Stripe has partnered with EasyPost and Shippo to help you get shipping rates directly from USPS, UPS, FedEx, and other carriers for your Stripe orders.

    You can represent products and orders within Stripe, rather than on your own site or through a third-party. If you are not yet familiar with the APIs for products and orders, we recommend that you first visit the Orders API documentation before diving into shipping cost calculations.

    To enable dynamic shipping rates for your orders, follow our guides to get started with EasyPost or Shippo. You can optionally read on below to learn how the integration works.

    How the integration works

    Stripe’s shipping integrations automatically manage everything necessary to calculate shipping costs for your orders. To help explain how the integration functions, read the high-level and technical overviews below. (The latter is intended for developers.)

    High-level overview

    When you create an order via Stripe, Stripe programmatically sends the following details to your shipping provider:

    • The specific versions (as SKUs) of the products being ordered
    • Your From address as specified in the Dashboard
    • The customer’s destination shipping address

    Stripe uses the addresses provided along with the weight and dimensions of the SKUs to calculate shipping costs through your shipping provider. The shipping provider returns the shipping methods to Stripe, which are added to the order in real-time. You can let your customers choose between the returned shipping methods, and Stripe will automatically update your order total as you select different shipping methods.

    The shipping rates calculated by the shipping provider depend on the size and weight of your products. It is therefore important that you provide Stripe with accurate dimensions for your products. You can do this from the Dashboard or the Stripe API. To use the Dashboard, navigate to a product page and click the Edit product button. Make sure that the Shippable checkbox is checked and fill in the width, height, length, and weight at the bottom of the page.

    To use the API, perform an update product request like the one below. In the API, we assume that width, height, and length are in inches while weight is in ounces:

    curl https://api.stripe.com/v1/products/pr_6rpcQjKz7PexY2 \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d package_dimensions[width]=15 \
       -d package_dimensions[height]=10 \
       -d package_dimensions[length]=15 \
       -d package_dimensions[weight]=32
    

    This shipping cost calculation service is usually provided free of charge by the shipping provider, so using a shipping integration with Stripe in most cases does not cost you anything. In addition to getting shipping rates, some providers let you purchase and print shipping labels online. This process varies between providers, and we encourage you to read the specific guides for EasyPost and Shippo to learn how label generation is supported.

    Technical overview

    Once you set up your shipping integration, you should automatically see multiple shipping methods show up in your order’s shipping_methods array. For example, the following request creates an order shippable to a US address:

    curl https://api.stripe.com/v1/orders \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d items[][parent]=easypost_test_sku \
       -d currency=usd \
       -d shipping[name]="Jenny Rosen" \
       -d shipping[address][line1]="123 Main Street" \
       -d shipping[address][postal_code]=94110 \
       -d shipping[address][city]="San Francisco" \
       -d shipping[address][state]=CA \
       -d shipping[address][country]=US \
       -d email="jenny@example.net"
    

    When processing the request, Stripe uses the shipping provider’s API to obtain shipping methods and includes them directly in the response. For this example, the response below includes three USPS shipping methods. Note that the first shipping method has been chosen by default and that the order total reflects the shipping costs in addition to the cost of the SKU.

    {
      "id": "or_18N3kWDAu10Yox5RuJQQpN69",
      "object": "order",
      "amount": 7559,
      ...
      "items": [
        {
          "object": "order_item",
          "amount": 6999,
          "currency": "usd",
          "description": "Slim Jeans",
          "parent": "easypost_test_sku",
          "quantity": 1,
          "type": "sku"
        },
        {
          "object": "order_item",
          "amount": 560,
          "currency": "usd",
          "description": "USPS: Priority (1 day delivery)",
          "parent": "rate_d3a94b44b02b48668a1d228a8c4982e6",
          "quantity": null,
          "type": "shipping"
        }
      ],
      ...
      "selected_shipping_method": "rate_d3a94b44b02b48668a1d228a8c4982e6",
      "shipping_methods": [
        {
          "id": "rate_d3a94b44b02b48668a1d228a8c4982e6",
          "amount": 560,
          "currency": "usd",
          "description": "USPS: Priority (1 day delivery)"
        },
        {
          "id": "rate_fc289c1131a94af58e19aa3e724d40c5",
          "amount": 595,
          "currency": "usd",
          "description": "USPS: ParcelSelect (2 day delivery)"
        },
        {
          "id": "rate_c8401086a10049fc9b3a9a37bcbcd5d4",
          "amount": 2066,
          "currency": "usd",
          "description": "USPS: Express (1 day delivery)"
        }
      ],
      ...
    }