Skip to main content

This topic builds on the concepts covered in the topic How to set up calculated shipping.

In this example, the seller adds an international shipping option to a fulfillment policy that already has a domestic free shipping option.

Here, the seller doesn't want to restrict the areas into where they sell, so they configure their international shipping option to ship "Worldwide". And because this policy allows buyers to have their orders shipped to regions from Albania to Zimbabwe, the seller has configured these shipping options as "calculated" shipping.

To configure a worldwide shipping option:

  1. Use createFulfillmentPolicy to create the fulfillment policy that will include your shipping policy.
  2. In the shippingOptions field, add a ShippingOption element to the existing DOMESTIC shipping option, and configure the following fields:
    • Set optionType to INTERNATIONAL.
    • Set costType to either FLAT_RATE or CALCULATED, depending on the service you'll use to ship the order.
  3. Populate the international ShippingOption element with your variation on what's shown in the following snippet of a fulfillment policy:
{
  "categoryTypes": [
    {
      "name": "ALL_EXCLUDING_MOTORS_VEHICLES"
    }
  ],
  "marketplaceId": "EBAY_US",
  "name": "Worldwide shipping options: Free domestic, CALCULATED int'l",
  "globalShipping": "false",
  "handlingTime": { 
    "unit" : "DAY",
    "value" : "1"
  },
  "shippingOptions": [
    {
      "costType": "FLAT_RATE",
      "optionType": "DOMESTIC",
      "shippingServices": [
        {
          "buyerResponsibleForShipping": "false",
          "freeShipping": "true",
          "shippingCarrierCode": "USPS",
          "shippingServiceCode": "USPSPriorityFlatRateBox",
          "shippingCost": {
            "currency": "USD",
            "value": "0.0"
          }
        }
      ]
    },
    {
      "costType": "CALCULATED",
      "optionType": "INTERNATIONAL",
      "shippingServices": [
        {
          "buyerResponsibleForShipping": "true",
          "freeShipping": "false",
          "shippingCarrierCode": "USPS",
          "shippingServiceCode": "USPSPriorityMailInternational",
          "shipToLocations": { 
            "regionIncluded": [
              {
                "regionName": "Worldwide"
              }
            ]
          }
        }
      ]
    }
  ]
}

Tip: The shipping services you specify must be able to support the optionType (either DOMESTIC or INTERNATIONAL) that's set in the parent ShippingOption element. In other words, you must specify an international shipping service if you're configuring an international shipping option.

Items of interest in this fulfillment policy:

  • First, you'll see there are two ShippingOption elements in the shippingOptions container; one configures domestic shipping options and the other configures international shipping options.
  • Second, the INTERNATIONAL ShippingOption element has shipToLocations container.

Note: You might notice that globalShipping is set to "false", which seems counter-intuitive when we are creating a fulfillment policy that supports INTERNATIONAL shipping. Keep in mind that the globalShipping field is used to indicate if the seller will use eBay's Global Shipping Program for their international shipments, and not an indication of whether or not the fulfillment policy supports shipping outside the domestic area.

The shipToLocations container

The shipToLocations container appears as a top-level field in the fulfillment policy, and also as a field buried within the shippingOptions configuration.

shipToLocations is a complex field serves a dual purpose. First, it specifies the "ship-to" regions that a shipping service covers. Then, you can also use it to define the regions where you do not ship. It has the following schema declaration:

  "shipToLocations": {
    "regionExcluded": [
      {
        "regionName": "string",
        "regionType": "RegionTypeEnum"
      }
    ],
    "regionIncluded": [
      {
        "regionName": "string",
        "regionType": "RegionTypeEnum"
      }
    ]
  }

This page discusses how to use shipToLocations to specify ship-to locations for a shippingServices. For more on shipToLocations, see How to exclude specific regions from included shipping areas.

Note: Make sure you understand the eBay international shipping policies by reviewing the International trading policy page.

Specifying the regions that a shipping service covers

When embedded in a shippingServices container, shipToLocations specifies the regions that the associated shipping service covers. This gives you the ability to configure each shipping service to support only the regions you specify.

Important! The shipToLocations field appears at both the top-level of the fulfillment policy and within each individual shippingOptions.shippingService container. Within a shippingService container, shipToLocations is used to specify the regions that the shipping service covers; it is not used to specify the regions that the service does not cover. Because of this, within a shippingService container, populate only the shipToLocations.regionIncluded field and do not populate it's sibling regionExcluded field.

Getting the values you can specify in regionIncluded.regionName

Every eBay marketplace supports its own set of regions that you can ship to from that marketplace. To determine the 'Ship-To' values that are valid for a particular marketplace, call GeteBayDetails with DetailName set to ShippingLocationDetails. Then, review the ShippingLocation fields in the response to determine the strings that you use in the regionIncluded.regionName field.

The regionIncluded field takes a list as input, so you can configure as many regions as you want with any regionIncluded field.