Setup custom shipping rate service

You can integrate a custom shipping service with Recharge to let shoppers use their preferred shipping carrier.

Contact your account manager to enable the Custom Shipping Rate Service beta on your store.

Setup

1. Go to the Integrations page and navigate to All Integrations

3. Select Get under Custom Shipping Rate Service

4. Fill in the URL and Header fields:

• Custom Shipping Rate Service URL (required) - This is the https url of your custom shipping rate service endpoint
• Custom Headers (optional) - Add any headers here that your service requires
• Secret Key (optional) - If your service requires a secret key, provide that here

Use custom shipping service in a shipping zone

1. Go to Shipping Settings

2. Under Shipping Setup, select the Use Recharge Zones, Rates and Integrations (Advanced), and follow the prompts. Once complete, proceed to the next step.

3. Navigate to Manage Zones and and add a rate to an existing zone (or create a zone if necessary).

4. Select Use a third-party app to calculate rates then select Custom Shipping Rate Service

5. Save your changes.

Note
You can add the custom shipping rate service to any number of shipping zones.

Creating custom shipping rates API integration

To use Custom Shipping Rates with Recharge, you will need middleware that can return and receive payloads that follow the guidelines in this article.

Requirements

Your Custom Shipping Rate API must send and receive data over HTTPS using the application/json header.

HMAC support for your application and the ability to send/receive custom headers are optional.

Request headers

Accept: application/json
Content-Type: application/json

Request

Recharge will send a request to your callback URL with the below fields.

Example request

{
  "rate": {
    "destination": {
      "country": "USA",
      "postal_code": "31904",
      "province": "GA",
      "city": "Columbus",
      "name": "Bill Harden",
      "address1": "1001 Red Maple Way",
      "address2": "Suite B"
    },
    "items": [{
      "name": "Vacuum Tube",
      "sku": "678968943234",
      "quantity": 1,
      "grams": 1000,
      "price": 1999,
      "vendor": "Bolton Hifi",
      "requires_shipping": true,
      "fulfillment_service": "manual",
      "product_id": 48447225880,
      "variant_id": 258644705304
    }],
    "currency": "USD",
    "locale": "en"
  }
}

Top-level field

Secondary levels

Destination properties

Response

Your application should send a 200 OK response and JSON payload with the following properties.

Any response to Recharge's request other than 200 will be considered an error.

Example response

{
   "rates": [
       {
           "service_name": "Expedited",
           "service_code": "EX",
           "total_price": "1295",
           "description": "expedited shipping",
           "currency": "USD",
       },
       {
           "service_name": "fedex-2dayground",
           "service_code": "2D",
           "total_price": "2934",
           "description": "fed ex 2 day",
           "currency": "USD",
       },
       {
           "service_name": "fedex-priorityovernight",
           "service_code": "1D",
           "total_price": "3587",
           "description": "fedex priority overnight",
           "currency": "USD",
       }
   ]
}

Top-level field

Secondary level

Response codes

See the following response codes for troubleshooting.

200 Response

If the service finds rates, return them along with a status of 200.

Example

{
   "rates": [
       {
           "service_name": "Expedited",
           "service_code": "EX",
           "total_price": "1295",
           "description": "expedited shipping",
           "currency": "USD",
       }
}

200 Response (Empty)

If the custom shipping rate service cannot find any shipping rates, return an empty rates list.

Example

{
    "rates":[]
}

401 Response

If the service expects an api_key token and it is missing or invalid, reply with a 401.

Example

{
    "error": "HMAC_INVALID_MISSING"
}

429 Response

If the service must rate limit, reply with 429.

Example

{
    "error": "RATE_LIMITED"
}

400 Response

If the payload sent to the service is invalid, return 400.

Other

Appropriate status code

{
    "error": "<error code>"
}

HMAC

You can add additional security to your shipping rate service using HMAC by providing a secret Recharge will then use to create a timestamp to append to the end of a URL.

https://example.com/?timestamp=785923045&hmac=somevaluehere

How to verify HMAC

When your app receives a request, you can check for this HMAC and verify it matches.

1. Receive the HMAC and timestamp from the request.

2. In your custom shipping rate service, create a new HMAC digest using your own copy of the secret key and the request timestamp as the message. Use SHA256 as the digest mode.

Example Message: timestamp=785923045

3. Compare this HMAC to the HMAC on the URL. If they match, then the message is valid.

If your client is expecting an HMAC and it was missing or invalid, you can reply with a 401 HTTP Status code.

Sample Python code

import hmac
from hashlib import sha256

secret_key = "your secret key"

# get timestamp and hmac from request
request_timestamp = request.args.get("timestamp")
request_hmac = request.args.get("hmac")

digest_maker = hmac.new(
    secret_key.encode("utf-8"),
    msg="timestamp={}".format(request_timestamp).encode("utf-8"),
    digestmod=sha256,
)

# If they do not match, the request is invalid
if digest_maker.hexdigest() != request_hmac:
    raise Exception()

Testing

You can can use our testing form to verify the custom shipping rate service.

Use the Service Tester on the integrations page to verify your service. We've pre-populated the request payload values, but you can change these. Click Test and the results of the request will be displayed in the form.