1. Extending Oracle Commerce
  2. Integrate with External Shipping Calculators
  3. Work with externally priced shipping methods

Work with externally priced shipping methods

Externally priced shipping methods can be created to represent each shipping method that can be returned by your shipping calculator service.

Unlike external shipping methods, creating externally priced shipping methods lets you take advantage of Oracle Commerce’s shipping promotion and tax calculation features.

Oracle Commerce determines which externally priced shipping methods are available based on internal rules. The available shipping methods and costs are sent to the shipping calculator service in the request. The shipping calculator service responds with some or all of the available methods and their prices and these available shipping methods are displayed to the shopper with the returned price. This section of this chapter provides detailed information on using this method. Refer also to Use Webhooks for additional information on using webhooks and the shipping calculator service.

With Oracle Commerce, you can create an externally priced shipping method through the administration interface Shipping Methods page available from the Settings list. This is done just like creating an internally priced shipping method except there is a drop-down list selection you can choose to indicate that you are specifying an externally priced shipping method. Also, you have availability to the “applies to shipping methods” picker in shipping promotions like you do with internally priced shipping methods.

Other things to note about this method include:

  • You have the ability to indicate that a shipping method is externally priced using both the Admin API and administration interface.
  • You have the ability to set all properties for external shipping methods in mostly the same way you can for internal methods. Some of the fallback behavior is different, however. See Enable fallback shipping methods for more information.
  • You have the ability to allow externally priced shipping methods to be marked as fallback methods. Externally priced shipping methods marked as fallback require prices. Pricing information is optional if the shipping method is externally priced but not a fallback. See Enable fallback shipping methods for more information.

Externally priced shipping methods behave the same as internally priced shipping methods. Shipping promotions and taxes are applied to externally priced shipping methods the same way as internally priced shipping methods.

The store recognizes the shipping regions associated with externally priced shipping methods as it does with internally priced shipping methods. The store should recognize the shipping regions associated with an externally priced shipping method that is considered unavailable based on internal rules but is returned by the shipping calculator. The service overrides the internal rules in this case and the resulting shipping method/storefront interface behaves the same as all other internally priced shipping methods.

Create externally priced shipping methods

As mentioned, you have the ability to create an externally priced shipping method using the administration interface. For information on how to do this, refer to Configure Shipping.

Configure the Shipping Calculator service for externally priced methods

Oracle Commerce invokes the Shipping Calculator function API to determine the available shipping method list. The list is then populated with a combination of available internal shipping methods and shipping methods returned in the Shipping Calculator response.

When the order is submitted, 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 Web API once for each shipping group.

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. A sample response is shown in this section of this chapter.

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

Understand how the shipping calculator Web API works

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

  • Most details about the order, including all its shipping groups. The request does not include certain payment details, such as credit card information. See Order Submit request example for a sample JSON 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 detailed order object 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.
  • The service request will also contain the externally priced shipping methods (along with their IDs and other properties) that are available based on internal rules.

Upon receiving the request, the shipping calculator service sends back a response which includes the externally priced shipping methods that are available for the current shopper/cart.

Note: The externally priced shipping methods in the response are identified by the ID sent in the request. Based on this ID, the response provides pricing and additional method information. In this way, the response format is different from what you might be used to when using existing external shipping methods. For more information, refer to the next two sections which describe the externally priced shipping methods response and request formats in more detail.

Understand the externally priced shipping methods shipping calculator service request

In more detail, the shipping service request provides the following information to the shipping calculator service:

  • The externally priced shipping methods eligible based on internal rules in the request. These will include the shipping method ID (see example) to identify them and other properties including the internal price if defined.
  • The complete cart/order definition if the full order capability has been requested.
  • The shopper profile
  • Shipping related properties for each item in the order such as dimensions and weight.

The following presents an example of a shipping calculator service request sent for externally priced shipping methods. The shipping method ID is displayed in bold in the example.

"availableExternallyPricedShippingMethods" : [ {
      "eligibleForProductWithSurcharges" : false,
      "ranges" : [ ],
      "associatedPriceListGroups" : [ {
        "id" : "defaultPriceGroup"
      } ],
      "displayName" : "Example External Shipping Method",
      "description" : "Example External Shipping Method",
      "allSites" : true,
      "sites" : [ ],
      "shippingMethodId" : "100001",
      "excludedCategoriesShippingCharge" : [ ],
      "isFallback" : false,
      "taxCode" : "100",
      "shippingGroupType" : "hardgoodShippingGroup"

Understand the externally priced shipping methods shipping calculator service response

Upon receiving the request, the shipping calculator service sends back a response which includes the externally priced shipping methods that are available for the current shopper/cart. These are identified by the ID received in the request.

The following example shows a shipping calculator service response for externally priced shipping methods. Again, the same shipping method ID is displayed in bold in the example.

"shippingMethods": [{
         "eligibleForProductWithSurcharges": false,
         "estimatedDeliveryDateGuaranteed": false,
         "displayName": "Example External Shipping Method",
         "shippingTax": 2,
         "currency": "USD",
         "shippingCost": 12.95,
         "shippingMethodId":"100001"
         "internationalDutiesTaxesFees": 0,
         "estimatedDeliveryDate": "2018-02-02 14:48:45 -0400",
         "shippingTotal": 14.95,
         "deliveryDays": 2,
         "taxcode": "100",
         "carrierId": "ON",
     }]

If a shipping method is returned in the response whose ID matches the one in the request then:

  • The properties returned in the response override the properties modeled internally. For example, the price and tax code returned by the shipping calculator will be used instead of the price and tax code modeled internally.
  • Oracle Commerce applies shipping promotions and calculate taxes for these shipping method and that generally behave the same as internal shipping methods except that they use the returned price and properties.

If a shipping method is returned in the response has an ID that does NOT match that in the request, or that does not have an ID then:

  • This shipping method is displayed with the name, price, tax code, and other properties as returned in the response.
  • Oracle Commerce treats these shipping methods as external shipping methods. Shipping promotions will not be applied. Other limitations may apply as described in the next section concerning external shipping methods.

A response may include a combination of externally priced and external shipping methods. Also, the shipping calculator may return a 400 error to indicate that the shipping address is invalid.

The following example shows an error response that might be returned when there is 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" }

Understand the contents of an order payload

If the shipping calculator service is triggered because an order is placed, a scheduled order is instantiated, or an order is approved, the order payload also includes details about the order and its shipping methods. See Order Submit request example for a sample JSON representation of an order in a webhook body.

The payload 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.

Some examples of the information that you find in the payload associated with this shipping method include

  • Promotion information
  • Shopper profile information
  • Product level information (for example length, width, weight, etc.)
  • Available externally priced shipping methods information

For more complete information and examples of the payload associated with this shipping method, refer to Learn about the APIs.