less than a minute read • Updated 11 minutes ago

Shipping Payload Reference

The JSON payload structure shared by Custom Shipping Code and Custom Shipping Endpoint.

Overview

Both Custom Shipping Code and Custom Shipping Endpoint receive the same JSON payload representing the current cart. In Custom Shipping Code, it's available as the cart global variable. For the Custom Shipping Endpoint, it's the POST body sent to your URL.

The payload includes everything about the current cart: items, the shipping address and store origin, totals, applied discounts, custom fields, and customer data. It follows the structure of Foxy's Hypermedia API cart resource.

Below is a reference of every section.

Top level fields

All fields at the root of the payload. The _embedded object containing the resources (shipment, items, discounts, etc.) is documented in the sections that follow.

Field	Description
`currency_code`	Cart currency code (e.g., `USD`, `EUR`). Custom rates must be in this currency.
`currency_symbol`	Display symbol (e.g., `$`, `€`)
`language`	Language code for the cart session
`locale_code`	Locale for number/date formatting (e.g., `en_US`)
`total_item_price`	Subtotal of all items (before shipping and taxes)
`total_tax`	Total tax amount
`total_shipping`	Total shipping amount
`total_order`	Grand total (items + tax + shipping)
`total_discount`	Total discount amount from coupons
`total_future_shipping`	Future shipping for subscription items
`total_future_item_price`	Future item price for subscription items
`billing_first_name`	Billing first name
`billing_last_name`	Billing last name
`billing_company`	Billing company
`billing_address1`	Billing street address line 1
`billing_address2`	Billing street address line 2
`billing_city`	Billing city
`billing_state`	Billing state/province
`billing_postal_code`	Billing ZIP/postal code
`billing_country`	Billing country code
`billing_phone`	Billing phone number
`shipping_first_name`	Shipping first name
`shipping_last_name`	Shipping last name
`shipping_company`	Shipping company
`shipping_address1`	Shipping street address line 1
`shipping_address2`	Shipping street address line 2
`shipping_city`	Shipping city
`shipping_state`	Shipping state/province
`shipping_postal_code`	Shipping ZIP/postal code
`shipping_country`	Shipping country code
`shipping_phone`	Shipping phone number
`customer_email`	Customer's email address
`customer_ip`	Customer's IP address
`ip_country`	Country name derived from IP
`use_customer_shipping_address`	Boolean: whether the customer is using a saved shipping address
`template_set_uri`	URI of the template set applied to this cart
`customer_uri`	URI of the customer resource
`payment_method_uri`	URI of the payment method
`session_name`	Session cookie name (e.g., `fcsid`)
`session_id`	Session ID string
`date_created`	Cart creation timestamp
`date_modified`	Cart last modified timestamp

For shipping logic, the fx:shipment embedded resource (below) is generally more useful than the top level shipping fields because it also includes the store's origin address, package details, and shipment totals.

fx:shipment

The _embedded["fx:shipment"] object is where you'll spend most of your time. It contains the customer's shipping address, the store's origin address, package details, and rolled up totals for the shipment.

Customer shipping address

Field	Description
`first_name`	Customer's first name
`last_name`	Customer's last name
`company`	Company name (empty string if not provided)
`email`	Customer's email
`customer_id`	Customer ID
`address_name`	Named address label (if using saved addresses)
`address1`	Street address line 1
`address2`	Street address line 2
`city`	City
`region`	State, province, or region code
`postal_code`	ZIP or postal code
`country`	Two letter country code (e.g., `US`, `GB`, `CA`)
`is_residential`	Boolean: whether the address is classified as residential

Origin address

Field	Description
`origin_region`	Store's origin state/province
`origin_postal_code`	Store's origin ZIP/postal code
`origin_country`	Store's origin country code

Package details

Field	Description
`package_count`	Number of packages (based on max package weight setting)
`package_weight`	Per package weight
`package_length`	Package length
`package_width`	Package width
`package_height`	Package height

Shipment totals

Field	Description
`item_count`	Total number of items in the cart
`total_weight`	Combined weight of all items
`total_item_price`	Subtotal (item prices before shipping and taxes)
`total_customs_value`	Total customs value for international shipments
`total_handling_fee`	Total handling fees from all categories
`total_flat_rate_shipping`	Total flat rate shipping from all categories
`total_tax`	Total tax
`total_shipping`	Total shipping (may be 0 when your code runs, since rates haven't been selected yet)
`total_price`	Grand total

Shipping service

Field	Description
`shipping_service_id`	ID of the currently selected shipping service (0 if none)
`shipping_service_description`	Description of the selected service (empty if none)

Accessing in Custom Shipping Code

const shipment = cart['_embedded']['fx:shipment'];
const country = shipment['country'];
const region = shipment['region'];
const postalCode = shipment['postal_code'];
const weight = shipment['total_weight'];
const subtotal = shipment['total_item_price'];
const itemCount = shipment['item_count'];
const isResidential = shipment['is_residential'];
const originCountry = shipment['origin_country'];

fx:items

The _embedded["fx:items"] array contains each item in the cart. Each item includes its own embedded category and options.

Core item fields

Field	Description
`name`	Product name
`code`	Product code/SKU
`price`	Unit price
`quantity`	Quantity in the cart
`weight`	Unit weight
`url`	Product URL
`image`	Product image URL

Dimensions

Field	Description
`length`	Item length (0 if not set)
`width`	Item width (0 if not set)
`height`	Item height (0 if not set)

Quantity limits

Field	Description
`quantity_min`	Minimum allowed quantity (0 = no minimum)
`quantity_max`	Maximum allowed quantity (0 = no maximum)

Shipping

Field	Description
`shipto`	Ship to address name (for multi ship orders)

Subscription fields

Field	Description
`subscription_frequency`	Subscription frequency string (empty if not a subscription)
`subscription_start_date`	Subscription start date
`subscription_next_transaction_date`	Next renewal date
`subscription_end_date`	Subscription end date
`is_future_line_item`	Boolean: whether this is a future dated subscription item

Discount fields

Field	Description
`discount_name`	Name of any item level discount
`discount_type`	Discount type
`discount_details`	Discount details string
`parent_code`	Parent product code (for bundled/child items)

Other

Field	Description
`item_category_uri`	URI of the item's category
`expires`	Expiration value (for downloadable items)
`date_created`	Item creation timestamp
`date_modified`	Item last modified timestamp

Embedded: fx:item_category

Each item embeds its full category object at _embedded["fx:item_category"]. This gives you access to the category's shipping configuration directly from the item.

Field	Description
`code`	Category code (e.g., `DEFAULT`)
`name`	Category display name
`item_delivery_type`	Delivery type: `shipped`, `flat_rate`, `pickup`, `downloaded`, `notshipped`
`default_weight`	Default weight for products in this category
`default_weight_unit`	Weight unit (`LBS`, `KG`)
`default_length_unit`	Length unit (`IN`, `CM`)
`shipping_flat_rate_type`	Flat rate type: `per_order` or `per_item`
`shipping_flat_rate`	Flat rate amount
`handling_fee_type`	Handling fee type: `none`, `flat_per_order`, `flat_per_item`, `flat_percent`, `flat_percent_with_minimum`
`handling_fee`	Handling fee flat amount
`handling_fee_minimum`	Minimum handling fee (for percentage types)
`handling_fee_percentage`	Handling fee percentage
`customs_value`	Default customs value

Embedded: fx:item_options

Each item embeds its options at _embedded["fx:item_options"]. Each option has:

Field	Description
`name`	Option name (e.g., `Colour`, `Size`)
`value`	Option value (e.g., `Red`, `Large`)
`price_mod`	Price modifier applied by this option
`weight_mod`	Weight modifier applied by this option

Accessing in Custom Shipping Code

const items = cart['_embedded']['fx:items'];
for (const item of items) {
  // Core fields
  const name = item['name'];
  const price = item['price'];
  const qty = item['quantity'];
  const weight = item['weight'];

  // Category
  const catCode = item['_embedded']['fx:item_category']['code'];
  const deliveryType = item['_embedded']['fx:item_category']['item_delivery_type'];

  // Options
  const options = item['_embedded']['fx:item_options'] || [];
  for (const opt of options) {
    console.log(opt['name'], opt['value'], opt['price_mod']);
  }

  // Subscription check
  if (item['subscription_frequency']) {
    // This is a subscription item
  }
}

fx:custom_fields

The _embedded["fx:custom_fields"] array contains custom data passed to shipping via h: session attributes, data-fc-shipping-custom-field checkout fields, or JavaScript events. Each entry is an object with name and value properties.

Note: this is an array, not a key/value object. You need to loop or use .find() to locate a specific field by name.

Accessing in Custom Shipping Code

const fields = cart['_embedded']['fx:custom_fields'] || [];

// Find a specific field
const giftWrap = fields.find(f => f['name'] === 'gift_wrap');
if (giftWrap && giftWrap['value'] === 'yes') {
  rates.price('+5');
}

See [Passing Custom Fields to Shipping] for how to add custom fields to the payload.

fx:discounts

The _embedded["fx:discounts"] array contains any coupons or discounts applied to the cart. Each entry has code and amount properties.

Accessing in Custom Shipping Code

const discounts = cart['_embedded']['fx:discounts'] || [];
for (const d of discounts) {
  if (d['code'] === 'freeshipping') {
    rates.hide();
    rates.add(11000, 0, '', 'Free Shipping');
  }
}

fx:shipping_results

The _embedded["fx:shipping_results"] array contains any shipping rates already returned by carriers or the custom endpoint before your Custom Shipping Code runs. This is typically empty when the custom endpoint receives the payload (since it runs in parallel with carriers), but in Custom Shipping Code it may be populated with carrier rates.

fx:customer

The _embedded["fx:customer"] object contains the customer's account data, including embedded attributes.

Field	Description
`id`	Customer ID
`first_name`	Customer first name
`last_name`	Customer last name
`email`	Customer email
`tax_id`	Tax ID (if provided)
`is_anonymous`	Boolean: whether this is a guest checkout
`last_login_date`	Last login timestamp
`date_created`	Account creation timestamp

Customer attributes are embedded at _embedded["fx:customer"]["_embedded"]["fx:attributes"]. Each attribute has name, value, and visibility properties. These are useful for loyalty programs or customer tier based shipping logic:

const customer = cart['_embedded']['fx:customer'];
const attrs = customer['_embedded']['fx:attributes'] || [];
const loyaltyLevel = attrs.find(a => a['name'] === 'Loyalty_Level');

if (loyaltyLevel && loyaltyLevel['value'] === 'Gold') {
  rates.add(10001, 0, '', 'Free Gold Member Shipping');
}

Example payload

Below is a condensed example showing the key parts of a typical payload. The _links sections (HAL hypermedia links) are omitted for readability as they're not typically used in shipping logic.

{
  "_embedded": {
    "fx:items": [
      {
        "name": "Fancy Widget",
        "code": "abc123",
        "price": 80.95,
        "quantity": 1,
        "weight": 30,
        "length": 0,
        "width": 0,
        "height": 0,
        "shipto": "",
        "image": "https://example.com/widget.jpg",
        "subscription_frequency": "",
        "is_future_line_item": false,
        "_embedded": {
          "fx:item_options": [
            {
              "name": "Colour",
              "value": "Sparkletoots",
              "price_mod": 0,
              "weight_mod": 0
            }
          ],
          "fx:item_category": {
            "code": "DEFAULT",
            "name": "Default for all products",
            "item_delivery_type": "shipped",
            "default_weight": 30,
            "default_weight_unit": "LBS",
            "shipping_flat_rate_type": "per_order",
            "shipping_flat_rate": 5,
            "handling_fee_type": "none",
            "handling_fee": 0,
            "handling_fee_percentage": 0
          }
        }
      }
    ],
    "fx:discounts": [],
    "fx:custom_fields": [],
    "fx:shipment": {
      "first_name": "Jane",
      "last_name": "Doe",
      "company": "NewCo",
      "address1": "555 Mulberry Dr",
      "city": "SAN DIEGO",
      "region": "CA",
      "postal_code": "92107",
      "country": "US",
      "is_residential": true,
      "origin_region": "NY",
      "origin_postal_code": "11110",
      "origin_country": "US",
      "item_count": 1,
      "total_weight": 30,
      "total_item_price": 80.95,
      "total_handling_fee": 0,
      "total_flat_rate_shipping": 0,
      "package_count": 1,
      "package_weight": 30
    },
    "fx:shipping_results": [],
    "fx:customer": {
      "id": 3456789,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "Jane@example.tld",
      "is_anonymous": false,
      "_embedded": {
        "fx:attributes": [
          {
            "name": "Loyalty_Points",
            "value": "5087",
            "visibility": "public"
          }
        ]
      }
    }
  },
  "total_item_price": 80.95,
  "total_tax": 0,
  "total_shipping": 0,
  "total_order": 80.95,
  "total_discount": 0,
  "currency_code": "USD",
  "currency_symbol": "$",
  "locale_code": "en_US",
  "billing_city": "SAN DIEGO",
  "billing_state": "CA",
  "billing_postal_code": "92107",
  "billing_country": "US",
  "customer_ip": "1.1.1.1",
  "ip_country": "United States"
}

Need Help?

Did this article answer your questions? Need help with anything? Please click below to contact us.

In This Article

Need Help?

Shipping Payload Reference

Overview

Top level fields

fx:shipment

Customer shipping address

Origin address

Package details

Shipment totals

Shipping service

Accessing in Custom Shipping Code

fx:items

Core item fields

Dimensions

Quantity limits

Shipping

Subscription fields

Discount fields

Other

Embedded: fx:item_category

Embedded: fx:item_options

Accessing in Custom Shipping Code

fx:custom_fields

Accessing in Custom Shipping Code

fx:discounts

Accessing in Custom Shipping Code

fx:shipping_results

fx:customer

Example payload

Need Help?