Work with external shipping methods

Unlike externally priced shipping methods, there is no need to create an internal representation for an external shipping method. This step can be omitted.

However, you may need to create a dummy internal shipping method if you plan to use external shipping methods only. This method is described in Configure Shipping. This step applies only to external shipping methods and is not needed for externally priced shipping methods.

Note: You can use external shipping methods if you do not need to take advantage of Oracle Commerce shipping promotion functionality. Using externally priced shipping methods, however, provides you with the best way to use the shipping calculator service and allows you to take full advantage of Oracle Commerce’s shipping promotions and tax calculation features.

Configure the Shipping Calculator service for external shipping methods

When the shopper selects the shipping methods list in the shopping cart, Commerce invokes the Shipping Calculator service. The list is then populated with the shipping methods returned in the service response. Then, when the shopper submits the order, Commerce invokes the service again to confirm that the selected shipping method and its associated cost are still valid. For an order with multiple shipping groups, Commerce invokes the service once for each shipping group.

The service sends the following data to the external shipping calculator:

Most details about the order, including all its shipping groups. The request does not include certain payment details, such as credit card information. See Understand webhooks and PCI DSS compliance for information about payment details that are excluded from the request. See Order Submit request example for a sample detailed representation of an order object in a Shipping Calculator service request body.
Previous versions of this service sent less order data in the payload of the request. Commerce still supports this version of the request by default. To send the more complete order representation in the request, you must first use the Admin API to issue a PUT request to /ccadmin/v1/merchant/clientConfiguration that sets the includeOrderDetailsInShippingMethodsPayload property to true.
Profile details for the registered shopper who placed the order. See Manage Shopper Profiles for a sample JSON representation of a shopper profile.

To send this data to the external shipping calculator service, you configure the service by specifying the URL, username, and password for accessing the service. (See Configure webhooks for details.) You must also configure the external service to read the request data, determine the appropriate shipping methods, and send a response that includes the following items:

The key orderIdReceived, whose value is a string that is the ID assigned to the order by Commerce.
The shippingMethods array, which contains available shipping methods and their associated costs.

The following sample shows a response with two available shipping methods:

{
  "orderIdReceived": "o460411",
  "shippingMethods": [
    {
      "shippingCost": 12.95,
      "shippingTax": 2.00,
      "shippingTotal": 14.95,
      "internationalDutiesTaxesFees": 0,
      "eligibleForProductWithSurcharges": true,
      "deliveryDays": 2,
      "estimatedDeliveryDateGuaranteed": false,
      "estimatedDeliveryDate": "2013-04-12 14:48:45 -0400",
      "displayName": "canadapost-overnight",
      "carrierId": "ON",
      "taxcode": "GT987",
      "currency": "USD"
    },
    {
      "shippingCost": 29.00,
      "shippingTax": 4.00,
      "shippingTotal": 33.00,
      "internationalDutiesTaxesFees": 0,
      "deliveryDays": 2,
      "estimatedDeliveryDateGuaranteed": false,
      "estimatedDeliveryDate": "2013-04-12 14:48:45 -0400",
      "displayName": "fedex-2dayground",
      "carrierId": "1D",
      "taxcode": "TD543",
      "currency": "USD"
    }
  ]
}

You can configure fallback shipping methods to display if Commerce cannot connect to the external system, for example in the event of an outage. See Enable fallback shipping methods for more information;

If no shipping methods are available based on the shipping address, the response returns an error. The following sample shows an error response that might be returned for an invalid shipping address.

{
  "errorCode": "00000000",
  "message": "Invalid shipping address",
  "errors": [
    {
      "errorCode": "28128",
      "message": "Update unsuccessful. Shipping address is not
        a valid ship-to address.",
      "status": "400"
    }
  ],
  "status": "400"
}

Implement the shipping calculator service for external shipping methods

In comparison to an externally priced shipping method, an external shipping method is a method returned by the external shipping calculator service that does not have an internal representation in the administration interface.

To set up the external shipping method integration with an external shipping calculator, perform the following steps:

Create shipping regions that specify where the carrier service will ship to. See Create shipping regions for more information.
Your store can offer a combination of internal and external shipping methods.
If your store uses only shipping methods returned from an external service, create a shipping method and associate it with the shipping regions you created in the previous step. See Create a shipping method for more information.

Keep the following points in mind as you create the shipping method:
- Give the shipping method an appropriate name, such as the descriptive name of a specific Region.
- By default, Commerce assumes that shipping prices received from the external service include all applicable taxes. Therefore, any tax value calculated by your integrated tax processor (based on the shipping method’s Tax Code property) is automatically overridden with 0 when the shipping price is displayed to the shopper.
However, you can configure Commerce so it uses your integrated tax processor (Avalara, Vertex, or an external tax processor) to calculate applicable shipping taxes for external shipping methods. This is the preferred method for calculating shipping taxes because shipping taxes are calculated the way you intended. See Calculate taxes for external shipping methods shipping calculator service for more information.
If you want to offer only shipping methods returned in the Shipping Calculator service response, customize the Order Summary widget JavaScript to hide the shipping method (based on its repositoryId property) you created in the previous step. See Developing Storefront Classic Widgets for Oracle Commerce for more information about customizing widgets.
Note: There is no way to hide this shipping method on the Agent Console. You must instruct Agent Console users to not select this shipping method.
Configure the Shipping Calculator service as described in Configure the Shipping Calculator service for external shipping methods section of chapter.

Once you have performed the steps in this procedure, the service is ready to use.

Understand the external shipping methods shipping calculator service request

With external shipping methods, you need to know the following information about the service request:

The request includes the complete cart/order definition
The request includes the shopper profile
The request includes shipping related properties for each item in the order such as dimensions and weight.

Understand the external shipping methods shipping calculator service response

With external shipping methods, you need to know the following information about the service request:

The response includes external shipping methods identified by display name. The price, tax code, and all properties are displayed as returned by the shipping calculator (since there is no internal representation).
Alternately the response may return a 400 error indicating an invalid shipping address (existing)

Oracle Commerce will not apply shipping promotions to these shipping methods.

Calculate taxes for external shipping methods shipping calculator service

By default, Commerce requires that shipping prices received from the external service include all applicable taxes. However, you can configure Commerce to use your integrated tax processor (Avalara, Vertex, or an external tax processor) to calculate applicable shipping taxes for shipping methods returned by the external shipping methods shipping calculator service. This is the preferred method for calculating shipping taxes because shipping taxes are calculated the way you intended.

You configure the Shipping Calculator webhook response to specify where shipping taxes are calculated by configuring the shipping system to include the appropriate value for the flag taxIncluded in the webhook response. The value should be one of the following:

true: Shipping taxes must be calculated by the external shipping service. This is the default value.
false: Shipping taxes are automatically calculated by the tax processor you integrated with Commerce.

The following sample webhook response body might be returned if taxIncluded is omitted:

orderIdReceived     "o30451"
shippingMethods
0
shippingCost     12.95
shippingTax     2
shippingTotal     14.95
internationalDutiesTaxesFees     0
eligibleForProductWithSurcharges     true
deliveryDays     2
estimatedDeliveryDateGuaranteed     false
estimatedDeliveryDate     "2018-09-12 14:48:45 -0400"
displayName     "canadapost-overnight"
carrierId     "ON"
taxcode     "GT987"
currency     "USD"

If taxIncluded is set to false, the response body might be:

orderIdReceived     "o30451"
shippingMethods
0
shippingCost     12.95
shippingTax     0
shippingTotal     12.95
internationalDutiesTaxesFees     0
eligibleForProductWithSurcharges     true
deliveryDays     2
estimatedDeliveryDateGuaranteed     false
estimatedDeliveryDate     "2018-09-12 14:48:45 -0400"
displayName     "canadapost-overnight"
carrierId     "ON"
taxcode     "GT987"
taxIncluded     "false"
currency     "USD"

See Configure Tax Processing for information about integrating with a tax processor.