The Interspire Shopping Cart Shipping Module Documentation is an introduction in to implementing additional shipping methods in to Interspire Shopping Cart. This guide assumes you have knowledge of PHP.

Interspire Shopping Cart 3.5 Required
This documentation has been written for the upcoming release of Interspire Shopping Cart 3.5. There are numerous changes between Interspire Shopping Cart 3.5 and earlier releases for modules.

Contents

  1. Introduction
  2. Flat-Rate and Real-Time Shipping
  3. Available Properties
  4. Available Methods
  5. Callbacks

Introduction

Shipping modules allow support for additional shipping methods to be integrated in to Interspire Shopping Cart. Shipping methods can be as simple as fixed or flat rate methods (such as Flat Rate per Order) or more complex shipping methods that retrieve real time quotes from external services (such as UPS or FedEx)

This document continues on from the Interspire Shopping Cart Modules Documentation which provides an overview of how Interspire Shopping Cart modules work and their structure.

Shipping modules exist within the /modules/shipping/ directory and extend upon the base ISC_SHIPPING class.

Flat-Rate and Real-Time Shipping

Interspire Shopping Cart supports two types of shipping calculations, flat-rate and real-time. In flat-rate methods, the shipping cost is calculated internally by the module based on one or more configuration settings. Real-time shipping quotes contact a third party service (such as FedEx or UPS) to return a shipping quote for the order.

The type of shipping module is defined as a property of the module itself. For a flat-rate shipping method, $this->_flatrate is set to true. For real-time shipping methods, this property of the module is set to false.

Available Properties

_destination_country

This property contains an array of the country name and country ISO code for the destination country for the shipping cost to be calculated.

_destination_state

This property contains an array of the state name and state ISO code (if it has one) for the destination state for the shipping cost to be calculated.

Available Methods

GetWeight

Returns the combined weight for the shipment.

GetNumProducts

Returns the number of products in this shipment.

GetCombinedShippingDimensions

Calculates and returns the box size required to hold all of the products if there’s more than one product in the shipment. This function will take the largest width and length of an item and sum the heights to return an estimated box size for shipping calculation.

The dimensions are returned as an array with width, height and length key/value pairs.

Callbacks

GetServiceQuotes

Returns: Array containing the list of shipping quotes that this module has returned. Each quote should be an ISC_SHIPPING_QUOTE object.

Shipping modules that can return more than one quote (for example, different delivery or shipping types such as Express and Standard rates) should implement this method. This method allows for multiple quotes to be passed back to Interspire Shopping Cart for the customer’s choice during checkout.

An array containing the list of shipping quotes should be returned. This array should contain an instance of the ISC_SHIPPING_QUOTE object for each shipping quote that can be returned. The example below loads a list of enabled delivery types, and loops through them. A shipping quote is retrieved for each delivery type by setting $this->_deliverytype and then calling $this->GetQuote() to calculate the quote for that particular delivery type.

function GetServiceQuotes()
{
	$QuoteList = array();
	$services = $this->GetValue("deliverytypes");
	if(!is_array($services) && $services != "") {
		$services = array($services);
	}
	foreach($services as $service) {
		// Set the service type
		$this->_deliverytype = $service;

		// Next actually retrieve the quote
		$result = $this->GetQuote();

		// Was it a valid quote?
		if(is_object($result)) {
			$QuoteList[] = $result;
		// Invalid quote, log the error
		} else {
			foreach($this->GetErrors() as $error) {
				$GLOBALS['ISC_CLASS_LOG']->LogSystemError(array('shipping', $this->_name), $this->_deliverytypes[$delivery_type].": " .GetLang('ShippingQuoteError'), $error);
			}
			$this->ResetErrors();
		}
	}
	return $QuoteList;
}

GetQuote

Returns: An ISC_SHIPPING_QUOTE object containing the shipping quote. False if there was an error returning the quote.

The GetQuote method for a shipping module will return a single shipping quote. This method should be implemented if the shipping module does not support multiple quotes being passed back (for example, the flat-rate by order module). The returned shipping quote should be an instance of the ISC_SHIPPING_QUOTE object. This module may also be implemented in modules that support multiple quotes and simply called by the GetServiceQuotes method to retrieve a single quote.

When instantiating the ISC_SHIPPING_QUOTE object, several arguments are supported. These are listed below in order of their acceptance to the quote object.

  • The ID of the shipping module returning the quote ($this->GetId())
  • The display name of the shipping module returning the quote ($this->GetDisplayName())
  • The dollar amount for the shipping quote
  • (Optional) The name of the service/delivery type for this quote (for example, Express)
  • (Optional) The transit time (in days) for this shipping quote.

If there was a problem retrieving the shipping quote, this function should return false. It may also call $this->SetError() to set any error messages.

An example GetQuote() method for a flat-rate shipping method (a fixed shipping cost per order) is shown below. This example will return a shipping quote for $this->_shippingcost, with a transit type of ‘Express Delivery’ and an estimated delivery time of 2 days.

function GetQuote()
{
	// Create a quote object
	$this->_shippingcost = CFloat($this->GetValue("shippingcost"));
	$fr_quote = new ISC_SHIPPING_QUOTE($this->GetId(), $this->GetName(), $this->_shippingcost, 'Express Delivery', 2);
	return $fr_quote;
}

TestQuoteForm

If this shipping module supports testing shipping quotes to check the returned shipping cost (via the control panel when editing a shipping module’s settings), this method should be implemented in the module. This method should output the HTML code necessary for the body of a quote test page.

For a shipping provider to show the “Test Shipping Quote” link, the class member variable $_showtestlink must be set to true. ($this->_showtestlink = true;)

Any templates loaded (by calling $this->ParseTemplate()) should reside within the modules template directory.

TestQuoteResult

If the above TestQuoteForm callback is implemented, this callback will be called when a user submits the test shipping quote window above. This module should contact the third party shipping service for quotes for the values the user previously entered on the form and if possible, show a list of available shipping methods/quotes.

Any templates loaded (by calling $this->ParseTemplate()) should reside within the modules template directory.

GetTrackingLink

Returns: String containing the tracking link for this item.

If a shipping module supports tracking shipped packages online, GetTracking link should return the URL to the tracking service to be shown on the “Order Status” page on the front end of the store.