====== Shipping "Hacks" and Advanced Techniques ======

<wrap important>The methods described on this page require advanced javascript knowledge, and are not officially supported.</wrap> They are included in our official wiki because certain shipping methods and functionality are not natively supported, and though we are working on radically improving our shipping functionality, in the meantime these methods may be great workarounds. Use with caution, test, and post in [[http://forum.foxycart.com/|our forum]] if you run into problems.

===== Multiple Custom Flat Rate Shipping Options  =====

The following functionality allows you to add and update any number of custom flat rate shipping options based on any criteria (eg: what categories are products in, total cost of the cart, shipping destination country). <wrap hi>This script is limited to flat rate shipping only.</wrap>

==== Step 1: Update Categories ====

Update all categories to 'Shipped using a flat rate fee' with a value of 0 in the 'Product Delivery Option' section.

==== Step 2: Add HTML ====

Add the following right after the ^^checkout^^ placeholder in your checkout template:

<code html>^^custom_begin^^
<div id="fc_custom_shipping_methods_container">
</div>
^^custom_end^^</code>

==== Step 3: Add Javascript ====

Add the following right before the closing ''</head>'' tag in your checkout template:

<code javascript><script type="text/javascript" charset="utf-8">
  //<![CDATA[
  $(document).ready(function() {
    $("input[name=shipping_service]").live('click', function(){
      shipping_service_description = jQuery(this).siblings(".fc_shipping_carrier").html();
      shipping_service_description += ((shipping_service_description == "") ? '' : ' ');
      shipping_service_description += jQuery(this).siblings(".fc_shipping_service").html();
      $("#shipping_details").val(shipping_service_description);
      // Launch FoxyCart functionality
      FC.checkout.updatePrice(-1);
    });
    
    /* BEGIN CUSTOM SHIPPING LOGIC */
    
    
    
    /* END CUSTOM SHIPPING LOGIC */
  });
  //]]>
</script>

<script type="text/javascript" charset="utf-8">
  //<![CDATA[
  /* Multiple Flat Rate Shipping Options Logic */
  
  // example: addShippingOption('local', 4.99, 'PostBox', 'Express Local');
  function addShippingOption(code, cost, carrier, service) {
    if (jQuery("#fc_shipping_methods_inner").length == 0) {
      addCustomShippingContainer();
    }
    var newShippingOption = '<label for="shipping_service_' + code + '" class="fc_radio"><input type="radio" class="fc_radio fc_required" value="' + code + '|' + cost + '" id="shipping_service_' + code + '" name="shipping_service" /><span class="fc_shipping_carrier">' + carrier + '</span><span class="fc_shipping_service">' + service + '</span><span class="fc_shipping_cost">' + FC.formatter.currency(cost, true) + '</span></label>';
    jQuery("#fc_shipping_methods_inner").append(newShippingOption);
  }
  
  // example: updateShippingOptionCost('local', 4);
  function updateShippingOptionCost(code, cost) {
    jQuery("input#shipping_service_" + code).val(code + '|' + cost).siblings("span.fc_shipping_cost").html(FC.formatter.currency(cost, true));
    FC.checkout.updatePrice(-1);
  }
  
  // example: removeShippingOption('local');
  function removeShippingOption(code) {
    jQuery("label[for=shipping_service_" + code + "]").remove();
    if (jQuery("#fc_shipping_methods_inner").html() == "") {
      removeCustomShippingContainer();
    }
    FC.checkout.updatePrice(-1);
  }
  
  function addCustomShippingContainer() {
    jQuery("#fc_custom_shipping_methods_container").html('<h2>Shipping Options</h2><div class="fc_row fc_shipping_methods_container" id="fc_shipping_methods_container"><div class="fc_radio_group_container fc_row fc_shipping_methods" id="fc_shipping_methods"><input type="hidden" value="0" id="shipping_service_id" name="shipping_service_id"><input type="text" style="display:none;" value="" id="shipping_service_description" name="shipping_service_description"><input type="text" value="" id="shipping_details" name="Shipping_Details" style="display:none;" /><div class="fc_shipping_methods_inner" id="fc_shipping_methods_inner"></div><label style="display: none;" class="fc_error" for="fc_shipping_methods">Please select a shipping method.</label></div></div>');
  }
  
  function removeCustomShippingContainer() {
    jQuery("#fc_custom_shipping_methods_container").html("");
    FC.checkout.updatePrice(-1);
  }
  //]]>
</script></code>

==== Step 4: Customise Shipping Options ====

Now the fun part, based on whatever criteria you want, add in the different shipping options you require for your site. Add your custom code between the ''/* BEGIN CUSTOM SHIPPING LOGIC */'' and ''/* END CUSTOM SHIPPING LOGIC */'' lines in the first script block. There are four functions available to you.

  ; ''addShippingOption()''
  : **Description:** Adds a shipping option to the checkout.
  : **Parameters:** ''code, cost, carrier, service''
  : **Example:** ''addShippingOption('local', 4.99, 'PostBox', 'Local Delivery');''
  : **Notes:** You don't have to provide both the carrier and the service parameters - but at least one of them is required.
  ; ''updateShippingOptionCost()''
  : **Description:** Updates the cost of a existing shipping option.
  : **Parameters:** ''code, cost''
  : **Example:** ''updateShippingOptionCost('local', 5.50);''
  ; ''removeShippingOption()''
  : **Description:** Removes an existing shipping option.
  : **Parameters:** ''code''
  : **Example:** ''removeShippingOption('local');''
  ; ''removeCustomShippingContainer()''
  : **Description:** Removes all existing shipping options.
  : **Parameters:** //none//
  : **Example:** ''removeCustomShippingContainer();''
  
=== Examples ===

== Example 1 ==

  - 3 default shipping options: standard and priority with one postal provider, and express with another.
  - If there are more than 5 products, remove the express option.
  - If the total weight of the cart is greater that 10, adjust the shipping costs.

<code javascript>addShippingOption('standard', 5, 'Postmaster', 'Standard Delivery');
addShippingOption('priority', 9.45, 'Postmaster', 'Priority Delivery');
addShippingOption('express', 10, 'PostPlus', 'Express (Next Day)');

if (fc_json.total_weight > 10) {
  updateShippingOptionCost('standard', 6);
  updateShippingOptionCost('priority', 10);
  updateShippingOptionCost('express', 11.99);
}

if (fc_json.product_count > 5) {
  removeShippingOption('express');
}</code>

== Example 2 ==

  - Postage is calculated as a base price per product, with each subsequent product adding an additional cost.
  - Two different groups of shipping options are presented, one for local delivery within the US, and one for international addresses based off of the shipping country.

<code javascript>
var postage = 0;
var country_code = (jQuery("#use_different_addresses").is(":checked") ? $("#shipping_country").val() : $("#customer_country").val());
if (country_code == "US") {
  postage = 10 + ((fc_json.product_count - 1) * 0.50);
  addShippingOption('standard', postage, 'USPS', 'Standard');
  
  postage = 12 + ((fc_json.product_count - 1) * 1.50);
  addShippingOption('express', postage, 'USPS', 'Express');
} else {
  postage = 15 + ((fc_json.product_count - 1) * 2);
  addShippingOption('intl', postage, 'USPS', 'International');
}
</code>