Passing Custom Fields to Shipping

Overview

When using a Custom Shipping Endpoint or Custom Shipping Code, you may need to pass extra information beyond the standard cart data (such as whether a customer requested signature on delivery, or a preferred pickup location). Foxy provides three ways to include custom data in the shipping payload.

Session attributes (h: prefix)

Any attribute added to the cart session with the h: prefix is automatically included in the shipping payload under the fx:custom_fields node. You add these as hidden inputs (or regular inputs) on your add to cart form:

<input type="hidden" name="h:gift_wrap" value="yes">

These values persist in the session and are sent with every shipping rate request.

Checkout fields (data-fc-shipping-custom-field)

For information you want to collect from the customer at checkout (not at add to cart time), add the data-fc-shipping-custom-field data attribute to your checkout form elements. This works with checkboxes, radio buttons, text inputs, and select dropdowns.

<input type="checkbox" id="sign_on_delivery" name="sign_on_delivery"
  value="Yes" {% if sign_on_delivery == "Yes" %}checked{% endif %}
  data-fc-shipping-custom-field>
<label for="sign_on_delivery">Signature on Delivery?</label>

Whenever a field with this attribute changes, Foxy automatically re requests shipping rates with the updated values included in the payload. If a checkout field shares the same name as an existing h: session attribute, the checkout field's value overwrites the session value for the shipping request.

JavaScript events

You can also inject or override custom fields programmatically using Foxy's shipping events:

FC.client.on("checkout-shipping-options-update", function(params) {
  params.custom_fields = { my_custom_attr: true };
});

The two relevant events are cart-shipping-options-update (for the cart/sidecart) and checkout-shipping-options-update (for the checkout page). Values set through these events overwrite matching session attributes but are themselves overwritten by any matching data-fc-shipping-custom-field checkout fields.

These same events can also be used to dynamically override the shipping origin address by setting params.store_address with country, region, and postal_code properties. This is useful if you ship from multiple locations and want to select the origin based on cart contents.