Custom Shipping Endpoint Overview

Overview

The Custom Shipping Endpoint lets you replace or augment Foxy's built in shipping by sending rate requests to a URL you control. When a customer enters their shipping address, Foxy POSTs a JSON payload with the full cart data to your endpoint. Your server calculates rates and returns them as JSON.

How to enable

1. 1

   Navigate to your store's Shipping page in the Foxy admin.

2. 2

   Under "Custom Shipping Endpoint (With Native Rates)," toggle it to Active and enter your endpoint's HTTPS URL.

3. 3

   Enable "Prevent shipping rate tampering" (recommended) to sign each rate and verify it hasn't been modified at submission.

4. 4

   Make sure any categories that should use the endpoint have their delivery type set to "Shipped using live shipping rates" with a default weight configured.

Since this delivery type also causes product weight to display in the cart, you can hide it by enabling "Customize cart display" in the admin's configuration page and deselecting "Show product weight."

Request payload

Foxy sends a POST request with a JSON body that follows the structure of the Hypermedia API's cart resource. The payload includes product details, the shipping address and origin, cart totals, custom fields, and applied discounts. See the [Shipping Payload Reference] for the full structure and field descriptions.

Response format

Success — return a JSON object with ok: true and an array of shipping results:

{
  "ok": true,
  "data": {
    "shipping_results": [
      {
        "service_id": 10001,
        "price": 10.55,
        "method": "FoxyPost",
        "service_name": "Standard"
      },
      {
        "service_id": 10002,
        "price": 20.99,
        "method": "FoxyPost",
        "service_name": "Express"
      }
    ]
  }
}

Rules for the response:

• service_id must be 10000 or higher and unique per rate.

• At least one of method or service_name is required.

• Only valid JSON should be output. Any non JSON content on the page (HTML, whitespace, error messages) will cause rates to fail.

Error — return a JSON object with ok: false and a details message:

{
  "ok": false,
  "details": "Sorry, we're unable to ship to that region"
}

Common errors

If customers see the error "This store has not been setup correctly to calculate shipping to this location with this weight," it means either no rates were returned from your endpoint or the response wasn't valid JSON. Check that your endpoint returns at least one rate (or an explicit error) for all requests, and that only the JSON response is output on the page.

Helper libraries

Foxy provides helper libraries that handle the request parsing and response formatting so you can focus on your shipping logic:

• PHP (5.3+) — Foxy/foxy-shipping-endpoint-php on GitHub. Provides a ShippingResponse class with add(), update(), hide(), show(), error(), and reset() methods.

• Node.js — Foxy/foxy-shipping-endpoint-node on GitHub (also available as the foxy-shipping-endpoint npm package). Same API surface, designed to pair with Express.

• AWS Lambda — The Node.js helper's GitHub wiki includes a guide for deploying to AWS Lambda with API Gateway. Lambda's permanent free tier (1 million requests/month and 400,000 GB seconds of compute) means this is effectively zero cost for most Foxy stores.

Currency note

Rates returned from your endpoint are not currency converted. You must return prices in the cart's currency, which is available in the payload's currency_code field.