Add shipping

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

Shipping address collection

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

Note:
Only Checkout with payment mode supports shipping options.

Create a Checkout session, adding some shipping rates to the shipping_options parameter. You can customize each shipping option with the shipping_rate_data parameter:

Parameter	Description
`type`	The type of calculation to used on the shipping rate. Can only be `fixed_amount` for now.
`fixed_amount[amount]`	How much to charge, in cents. Set it to `0` if you want to offer free shipping.
`fixed_amount[currency]`	Which currency to charge in (for example, `usd`, `eur`).
`display_name`	The name of the shipping rate, to display to the customer.
`delivery_estimate`	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.

Note:

The first option in the shipping_options array is pre-selected for the customer when they land on the checkout page.

console

curl https://api.payske.com/v1/checkout/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "shipping_address_collection[allowed_countries][0]"=US \
  -d "shipping_address_collection[allowed_countries][1]"=CA \
  -d "shipping_options[0][shipping_rate_data][type]"=fixed_amount \
  -d "shipping_options[0][shipping_rate_data][fixed_amount][amount]"=0 \
  -d "shipping_options[0][shipping_rate_data][fixed_amount][currency]"=usd \
  -d "shipping_options[0][shipping_rate_data][display_name]"="Free shipping" \
  -d "shipping_options[0][shipping_rate_data][delivery_estimate][minimum][unit]"=business_day \
  -d "shipping_options[0][shipping_rate_data][delivery_estimate][minimum][value]"=5 \
  -d "shipping_options[0][shipping_rate_data][delivery_estimate][maximum][unit]"=business_day \
  -d "shipping_options[0][shipping_rate_data][delivery_estimate][maximum][value]"=7 \
  -d "shipping_options[1][shipping_rate_data][type]"=fixed_amount \
  -d "shipping_options[1][shipping_rate_data][fixed_amount][amount]"=1500 \
  -d "shipping_options[1][shipping_rate_data][fixed_amount][currency]"=usd \
  -d "shipping_options[1][shipping_rate_data][display_name]"="Next day air" \
  -d "shipping_options[1][shipping_rate_data][delivery_estimate][minimum][unit]"=business_day \
  -d "shipping_options[1][shipping_rate_data][delivery_estimate][minimum][value]"=1 \
  -d "shipping_options[1][shipping_rate_data][delivery_estimate][maximum][unit]"=business_day \
  -d "shipping_options[1][shipping_rate_data][delivery_estimate][maximum][value]"=1 \
  -d "line_items[0][price_data][currency]"=usd \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][unit_amount]"=2000 \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

console

payske checkout sessions create  \
  -d "shipping_address_collection[allowed_countries][0]"=US \
  -d "shipping_address_collection[allowed_countries][1]"=CA \
  -d "shipping_options[0][shipping_rate_data][type]"=fixed_amount \
  -d "shipping_options[0][shipping_rate_data][fixed_amount][amount]"=0 \
  -d "shipping_options[0][shipping_rate_data][fixed_amount][currency]"=usd \
  -d "shipping_options[0][shipping_rate_data][display_name]"="Free shipping" \
  -d "shipping_options[0][shipping_rate_data][delivery_estimate][minimum][unit]"=business_day \
  -d "shipping_options[0][shipping_rate_data][delivery_estimate][minimum][value]"=5 \
  -d "shipping_options[0][shipping_rate_data][delivery_estimate][maximum][unit]"=business_day \
  -d "shipping_options[0][shipping_rate_data][delivery_estimate][maximum][value]"=7 \
  -d "shipping_options[1][shipping_rate_data][type]"=fixed_amount \
  -d "shipping_options[1][shipping_rate_data][fixed_amount][amount]"=1500 \
  -d "shipping_options[1][shipping_rate_data][fixed_amount][currency]"=usd \
  -d "shipping_options[1][shipping_rate_data][display_name]"="Next day air" \
  -d "shipping_options[1][shipping_rate_data][delivery_estimate][minimum][unit]"=business_day \
  -d "shipping_options[1][shipping_rate_data][delivery_estimate][minimum][value]"=1 \
  -d "shipping_options[1][shipping_rate_data][delivery_estimate][maximum][unit]"=business_day \
  -d "shipping_options[1][shipping_rate_data][delivery_estimate][maximum][value]"=1 \
  -d "line_items[0][price_data][currency]"=usd \
  -d "line_items[0][price_data][product_data][name]"="T-shirt" \
  -d "line_items[0][price_data][unit_amount]"=2000 \
  -d "line_items[0][quantity]"=1 \
  --mode=payment \
  --success-url="https://example.com/success" \
  --cancel-url="https://example.com/cancel"

ruby

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://account.payske.com/api/key
Payske.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Payske::Checkout::Session.create(
  {
    shipping_address_collection: {allowed_countries: ['US', 'CA']},
    shipping_options: [
      {
        shipping_rate_data: {
          type: 'fixed_amount',
          fixed_amount: {amount: 0, currency: 'usd'},
          display_name: 'Free shipping',
          delivery_estimate: {
            minimum: {unit: 'business_day', value: 5},
            maximum: {unit: 'business_day', value: 7},
          },
        },
      },
      {
        shipping_rate_data: {
          type: 'fixed_amount',
          fixed_amount: {amount: 1500, currency: 'usd'},
          display_name: 'Next day air',
          delivery_estimate: {
            minimum: {unit: 'business_day', value: 1},
            maximum: {unit: 'business_day', value: 1},
          },
        },
      },
    ],
    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',
  },
)

python

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://account.payske.com/api/key
import payske
payske.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

payske.checkout.Session.create(
  shipping_address_collection={"allowed_countries": ["US", "CA"]},
  shipping_options=[
    {
      "shipping_rate_data": {
        "type": "fixed_amount",
        "fixed_amount": {"amount": 0, "currency": "usd"},
        "display_name": "Free shipping",
        "delivery_estimate": {
          "minimum": {"unit": "business_day", "value": 5},
          "maximum": {"unit": "business_day", "value": 7},
        },
      },
    },
    {
      "shipping_rate_data": {
        "type": "fixed_amount",
        "fixed_amount": {"amount": 1500, "currency": "usd"},
        "display_name": "Next day air",
        "delivery_estimate": {
          "minimum": {"unit": "business_day", "value": 1},
          "maximum": {"unit": "business_day", "value": 1},
        },
      },
    },
  ],
  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",
)

php

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://account.payske.com/api/key
$payske = new \Payske\PayskeClient('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$payske->checkout->sessions->create(
  [
    'shipping_address_collection' => ['allowed_countries' => ['US', 'CA']],
    'shipping_options' => [
      [
        'shipping_rate_data' => [
          'type' => 'fixed_amount',
          'fixed_amount' => ['amount' => 0, 'currency' => 'usd'],
          'display_name' => 'Free shipping',
          'delivery_estimate' => [
            'minimum' => ['unit' => 'business_day', 'value' => 5],
            'maximum' => ['unit' => 'business_day', 'value' => 7],
          ],
        ],
      ],
      [
        'shipping_rate_data' => [
          'type' => 'fixed_amount',
          'fixed_amount' => ['amount' => 1500, 'currency' => 'usd'],
          'display_name' => 'Next day air',
          'delivery_estimate' => [
            'minimum' => ['unit' => 'business_day', 'value' => 1],
            'maximum' => ['unit' => 'business_day', 'value' => 1],
          ],
        ],
      ],
    ],
    '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',
  ]
);

java

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://account.payske.com/api/key
Payske.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setShippingAddressCollection(
      SessionCreateParams.ShippingAddressCollection.builder()
        .addAllowedCountry(
          SessionCreateParams.ShippingAddressCollection.AllowedCountry.US
        )
        .addAllowedCountry(
          SessionCreateParams.ShippingAddressCollection.AllowedCountry.CA
        )
        .build()
    )
    .addShippingOption(
      SessionCreateParams.ShippingOption.builder()
        .setShippingRateData(
          SessionCreateParams.ShippingOption.ShippingRateData.builder()
            .setType(
              SessionCreateParams.ShippingOption.ShippingRateData.Type.FIXED_AMOUNT
            )
            .setFixedAmount(
              SessionCreateParams.ShippingOption.ShippingRateData.FixedAmount.builder()
                .setAmount(0L)
                .setCurrency("usd")
                .build()
            )
            .setDisplayName("Free shipping")
            .setDeliveryEstimate(
              SessionCreateParams.ShippingOption.ShippingRateData.DeliveryEstimate.builder()
                .setMinimum(
                  SessionCreateParams.ShippingOption.ShippingRateData.DeliveryEstimate.Minimum.builder()
                    .setUnit(
                      SessionCreateParams.ShippingOption.ShippingRateData.DeliveryEstimate.Minimum.Unit.BUSINESS_DAY
                    )
                    .setValue(5L)
                    .build()
                )
                .setMaximum(
                  SessionCreateParams.ShippingOption.ShippingRateData.DeliveryEstimate.Maximum.builder()
                    .setUnit(
                      SessionCreateParams.ShippingOption.ShippingRateData.DeliveryEstimate.Maximum.Unit.BUSINESS_DAY
                    )
                    .setValue(7L)
                    .build()
                )
                .build()
            )
            .build()
        )
        .build()
    )
    .addShippingOption(
      SessionCreateParams.ShippingOption.builder()
        .setShippingRateData(
          SessionCreateParams.ShippingOption.ShippingRateData.builder()
            .setType(
              SessionCreateParams.ShippingOption.ShippingRateData.Type.FIXED_AMOUNT
            )
            .setFixedAmount(
              SessionCreateParams.ShippingOption.ShippingRateData.FixedAmount.builder()
                .setAmount(1500L)
                .setCurrency("usd")
                .build()
            )
            .setDisplayName("Next day air")
            .setDeliveryEstimate(
              SessionCreateParams.ShippingOption.ShippingRateData.DeliveryEstimate.builder()
                .setMinimum(
                  SessionCreateParams.ShippingOption.ShippingRateData.DeliveryEstimate.Minimum.builder()
                    .setUnit(
                      SessionCreateParams.ShippingOption.ShippingRateData.DeliveryEstimate.Minimum.Unit.BUSINESS_DAY
                    )
                    .setValue(1L)
                    .build()
                )
                .setMaximum(
                  SessionCreateParams.ShippingOption.ShippingRateData.DeliveryEstimate.Maximum.builder()
                    .setUnit(
                      SessionCreateParams.ShippingOption.ShippingRateData.DeliveryEstimate.Maximum.Unit.BUSINESS_DAY
                    )
                    .setValue(1L)
                    .build()
                )
                .build()
            )
            .build()
        )
        .build()
    )
    .addLineItem(
      SessionCreateParams.LineItem.builder()
        .setPriceData(
          SessionCreateParams.LineItem.PriceData.builder()
            .setCurrency("usd")
            .setProductData(
              SessionCreateParams.LineItem.PriceData.ProductData.builder()
                .setName("T-shirt")
                .build()
            )
            .setUnitAmount(2000L)
            .build()
        )
        .setQuantity(1L)
        .build()
    )
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setSuccessUrl("https://example.com/success")
    .setCancelUrl("https://example.com/cancel")
    .build();

Session session = Session.create(params);

typescript

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://account.payske.com/api/key
const payske = require('payske')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const session = await payske.checkout.sessions.create({
  shipping_address_collection: {allowed_countries: ['US', 'CA']},
  shipping_options: [
    {
      shipping_rate_data: {
        type: 'fixed_amount',
        fixed_amount: {amount: 0, currency: 'usd'},
        display_name: 'Free shipping',
        delivery_estimate: {
          minimum: {unit: 'business_day', value: 5},
          maximum: {unit: 'business_day', value: 7},
        },
      },
    },
    {
      shipping_rate_data: {
        type: 'fixed_amount',
        fixed_amount: {amount: 1500, currency: 'usd'},
        display_name: 'Next day air',
        delivery_estimate: {
          minimum: {unit: 'business_day', value: 1},
          maximum: {unit: 'business_day', value: 1},
        },
      },
    },
  ],
  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',
});

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://account.payske.com/api/key
payske.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &payske.CheckoutSessionParams{
  ShippingAddressCollection: &payske.CheckoutSessionShippingAddressCollectionParams{
    AllowedCountries: []*string{payske.String("US"), payske.String("CA")},
  },
  ShippingOptions: []*payske.CheckoutSessionShippingOptionParams{
    &payske.CheckoutSessionShippingOptionParams{
      ShippingRateData: &payske.CheckoutSessionShippingOptionShippingRateDataParams{
        Type: payske.String("fixed_amount"),
        FixedAmount: &payske.CheckoutSessionShippingOptionShippingRateDataFixedAmountParams{
          Amount: payske.Int64(0),
          Currency: payske.String(string(payske.CurrencyUSD)),
        },
        DisplayName: payske.String("Free shipping"),
        DeliveryEstimate: &payske.CheckoutSessionShippingOptionShippingRateDataDeliveryEstimateParams{
          Minimum: &payske.CheckoutSessionShippingOptionShippingRateDataDeliveryEstimateMinimumParams{
            Unit: payske.String("business_day"),
            Value: payske.Int64(5),
          },
          Maximum: &payske.CheckoutSessionShippingOptionShippingRateDataDeliveryEstimateMaximumParams{
            Unit: payske.String("business_day"),
            Value: payske.Int64(7),
          },
        },
      },
    },
    &payske.CheckoutSessionShippingOptionParams{
      ShippingRateData: &payske.CheckoutSessionShippingOptionShippingRateDataParams{
        Type: payske.String("fixed_amount"),
        FixedAmount: &payske.CheckoutSessionShippingOptionShippingRateDataFixedAmountParams{
          Amount: payske.Int64(1500),
          Currency: payske.String(string(payske.CurrencyUSD)),
        },
        DisplayName: payske.String("Next day air"),
        DeliveryEstimate: &payske.CheckoutSessionShippingOptionShippingRateDataDeliveryEstimateParams{
          Minimum: &payske.CheckoutSessionShippingOptionShippingRateDataDeliveryEstimateMinimumParams{
            Unit: payske.String("business_day"),
            Value: payske.Int64(1),
          },
          Maximum: &payske.CheckoutSessionShippingOptionShippingRateDataDeliveryEstimateMaximumParams{
            Unit: payske.String("business_day"),
            Value: payske.Int64(1),
          },
        },
      },
    },
  },
  LineItems: []*payske.CheckoutSessionLineItemParams{
    &payske.CheckoutSessionLineItemParams{
      PriceData: &payske.CheckoutSessionLineItemPriceDataParams{
        Currency: payske.String(string(payske.CurrencyUSD)),
        ProductData: &payske.CheckoutSessionLineItemPriceDataProductDataParams{
          Name: payske.String("T-shirt"),
        },
        UnitAmount: payske.Int64(2000),
      },
      Quantity: payske.Int64(1),
    },
  },
  Mode: payske.String(string(payske.CheckoutSessionModePayment)),
  SuccessURL: payske.String("https://example.com/success"),
  CancelURL: payske.String("https://example.com/cancel"),
};
result, _ := session.New(params);

csharp

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://account.payske.com/api/key
PayskeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new SessionCreateOptions
{
    ShippingAddressCollection = new SessionShippingAddressCollectionOptions
    {
        AllowedCountries = new List<string> { "US", "CA" },
    },
    ShippingOptions = new List<SessionShippingOptionOptions>
    {
        new SessionShippingOptionOptions
        {
            ShippingRateData = new SessionShippingOptionShippingRateDataOptions
            {
                Type = "fixed_amount",
                FixedAmount = new SessionShippingOptionShippingRateDataFixedAmountOptions
                {
                    Amount = 0,
                    Currency = "usd",
                },
                DisplayName = "Free shipping",
                DeliveryEstimate = new SessionShippingOptionShippingRateDataDeliveryEstimateOptions
                {
                    Minimum = new SessionShippingOptionShippingRateDataDeliveryEstimateMinimumOptions
                    {
                        Unit = "business_day",
                        Value = 5,
                    },
                    Maximum = new SessionShippingOptionShippingRateDataDeliveryEstimateMaximumOptions
                    {
                        Unit = "business_day",
                        Value = 7,
                    },
                },
            },
        },
        new SessionShippingOptionOptions
        {
            ShippingRateData = new SessionShippingOptionShippingRateDataOptions
            {
                Type = "fixed_amount",
                FixedAmount = new SessionShippingOptionShippingRateDataFixedAmountOptions
                {
                    Amount = 1500,
                    Currency = "usd",
                },
                DisplayName = "Next day air",
                DeliveryEstimate = new SessionShippingOptionShippingRateDataDeliveryEstimateOptions
                {
                    Minimum = new SessionShippingOptionShippingRateDataDeliveryEstimateMinimumOptions
                    {
                        Unit = "business_day",
                        Value = 1,
                    },
                    Maximum = new SessionShippingOptionShippingRateDataDeliveryEstimateMaximumOptions
                    {
                        Unit = "business_day",
                        Value = 1,
                    },
                },
            },
        },
    },
    LineItems = new List<SessionLineItemOptions>
    {
        new SessionLineItemOptions
        {
            PriceData = new SessionLineItemPriceDataOptions
            {
                Currency = "usd",
                ProductData = new SessionLineItemPriceDataProductDataOptions
                {
                    Name = "T-shirt",
                },
                UnitAmount = 2000,
            },
            Quantity = 1,
        },
    },
    Mode = "payment",
    SuccessUrl = "https://example.com/success",
    CancelUrl = "https://example.com/cancel",
};
var service = new SessionService();
service.Create(options);

Your customers see a shipping selector on the checkout page:

What your customer sees.

Delivery estimates

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 delivery_estimate.minimum and delivery_estimate.maximum values.

Delivery Estimate	Minimum	Maximum
1 day	`{ unit: 'day', value: 1,}`	`{ unit: 'day', value: 1,}`
1 business day	`{ unit: 'business_day', value: 1,}`	`{ unit: 'business_day', value: 1,}`
At least 2 business days	`{ unit: 'business_day', value: 2,}`	`null`
3 to 7 days	`{ unit: 'day', value: 3,}`	`{ unit: 'day', value: 7,}`
4 to 8 hours	`{ unit: 'hour', value: 4,}`	`{ unit: 'hour', value: 8,}`
4 hours to 2 business days	`{ unit: 'hour', value: 4,}`	`{ unit: 'business_day', value: 2,}`

Add shipping ​

Shipping address collection ​

Create a Checkout session with shipping options ​

Delivery estimates ​

Add shipping

Shipping address collection

Create a Checkout session with shipping options

Delivery estimates