Multi-Carrier API Integration Checklist

FedEx · ShipHawk · Canada Post

Who this is for: Someone building a shipping aggregator that connects to FedEx, ShipHawk, and Canada Post — and wants to know exactly what each carrier needs and how they differ.

Table of Contents

1. What is a Shipping Aggregator?
2. Authentication — "Prove who you are"
3. Endpoints & Protocol — "Where do you send requests?"
4. Rate Request — "Ask for a price quote"
5. Rate Response — "Reading the quote back"
6. Label Generation — "Book the shipment"
7. Document Rendering — "What does the label look like?"
8. Error Handling — "When things go wrong"
9. Normalisation — "Making all three speak the same language"

1. What is a Shipping Aggregator?

A shipping aggregator sits in the middle between your app and multiple carrier APIs. Instead of your code talking to FedEx, ShipHawk, and Canada Post separately, it talks to one aggregator that handles all three.

Your App
   │
   ▼
[ Aggregator Layer ]
   │          │          │
FedEx     ShipHawk   Canada Post

The goal of this checklist is to document everything the aggregator layer needs to know about each carrier.

2. Authentication — "Prove who you are"

Before you can call any API, you need to prove your identity. Each carrier does this differently.

How Each Carrier Handles Auth

FedEx — Step-by-step (it's the most complex)

FedEx requires you to get a token first, then use it:

Step 1: POST https://apis.fedex.com/oauth/token
        Body: grant_type=client_credentials
              &client_id=YOUR_ID
              &client_secret=YOUR_SECRET

Step 2: You get back: { "access_token": "abc123...", "expires_in": 3600 }

Step 3: Use in every API call:
        Authorization: Bearer abc123...

Step 4: After 55 minutes, repeat Step 1 to get a fresh token.

⚠️ Don't call /oauth/token before every API request — that wastes time and hits rate limits. Cache the token and refresh it 5 minutes before it expires.

ShipHawk — Simplest

Just put your key in every request header:

X-Api-Key: your_api_key_here

Canada Post — Base64 Encoding

Take your username and password, join them with a colon, and encode as Base64:

base64("username:password") → "dXNlcm5hbWU6cGFzc3dvcmQ="

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Sandbox (Test) Credentials

Always test in sandbox before going live. Each carrier has a separate sandbox:

Security Rules (for all carriers)

• Never put credentials in your source code
• Store them in a secrets manager (e.g. AWS Secrets Manager)
• Never log tokens or API keys
• Use HTTPS only — all three carriers require it

3. Endpoints & Protocol — "Where do you send requests?"

Base URLs

Key Endpoints

Notice: Cancel uses PUT for FedEx, DELETE for ShipHawk, and POST for Canada Post. Your aggregator must route correctly.

Big Difference — Data Format

This is the most important protocol difference:

Canada Post also uses versioned media types in headers instead of just application/json:

Content-Type: application/vnd.cpc.ship.rate-v4+xml
Accept:       application/vnd.cpc.ship.rate-v4+xml

Your aggregator will need an XML adapter specifically for Canada Post.

4. Rate Request — "Ask for a price quote"

A rate request says: "I want to ship a 2kg box from Toronto to Vancouver — how much?"

Required Fields (all carriers need these)

Unit Differences — Watch Out!

Convert everything to the carrier's required unit before sending. For Canada Post: inches × 2.54 = cm.

Optional But Useful Fields

5. Rate Response — "Reading the quote back"

After sending a rate request, you get back a list of shipping options with prices.

Key Response Fields

Important: ShipHawk is the only carrier that gives you a rate_id. Store it — you'll need it to book the shipment. For FedEx and Canada Post, you must re-request rates at booking time.

Service Code Equivalents

6. Label Generation — "Book the shipment"

Once a customer picks a rate, you create a shipment. This returns a tracking number and a shipping label.

Create Shipment Endpoints

Multi-Package Shipping

Cancelling a Shipment

⚠️ Canada Post specific: You must call Transmit Shipments before Canada Post will accept a pickup. Voiding is only possible before transmitting. Once transmitted, labels cannot be voided via API.

7. Document Rendering — "What does the label look like?"

Label Formats Supported

Label Sizes

How the Label is Delivered

Best practice: Always save the label to your own storage immediately after creation. Don't rely on carrier links staying alive.

FedEx Label Certification (Required!)

Before going live with FedEx, you must submit test labels to FedEx for review:

• Submit PDF, PNG, and ZPL formats scanned at 600 DPI
• Email to: label@fedex.com
• FedEx will approve before you can use production

8. Error Handling — "When things go wrong"

HTTP Status Codes

⚠️ Canada Post gotcha: Even a 200 OK can contain error messages inside the XML <messages> block. Always inspect the body, don't trust the status code alone.

Error Body Formats (they look different!)

FedEx (JSON):

{
  "errors": [
    { "code": "WEIGHT.EXCEEDS.MAXIMUM", "message": "Weight exceeds maximum limit" }
  ]
}

ShipHawk (JSON):

{
  "errors": [{ "message": "weight must be less than 150 lbs" }]
}

Canada Post (XML inside a 400 response):

<messages>
  <message>
    <code>7007</code>
    <description>Weight value is invalid</description>
  </message>
</messages>

Your aggregator should normalise all of these to a common format:

{ "carrier": "canadapost", "code": "PACKAGE_WEIGHT_EXCEEDED", "message": "...", "retryable": false }

Retry Strategy

Exponential back-off means you wait a little longer each time you retry, so you don't hammer the server:

Attempt 1 → fail → wait 1 second
Attempt 2 → fail → wait 2 seconds
Attempt 3 → fail → wait 4 seconds → give up

9. Normalisation — "Making all three speak the same language"

This is the hardest part of building an aggregator. Here's a summary of the key differences you must handle.

The Biggest Differences at a Glance

Standard Workflow in the Aggregator

Every shipment follows the same steps, regardless of carrier:

1. getRates(origin, destination, packages)
      │
      ├─ Translates to FedEx rate request (JSON)
      ├─ Translates to ShipHawk rate request (JSON)
      └─ Translates to Canada Post rate request (XML)
      │
      ▼
2. normaliseRates(fedexRates, shiphawkRates, canadaPostRates)
   → Returns unified list: [{ carrier, serviceCode, totalCharge, transitDays, ... }]
      │
      ▼
3. User selects a rate
      │
      ▼
4. createShipment(selectedRate, addresses, packages)
      │
      ├─ FedEx: POST /ship/v1/shipments
      ├─ ShipHawk: POST /api/v4/shipments (pass rate_id)
      └─ Canada Post: POST /rs/.../shipment (XML)
      │
      ▼
5. getLabel() → normalise to LabelArtifact { url?, base64?, mimeType }
      │
      ▼
6. Save label to your own storage immediately

Mandatory Steps by Carrier

Service Code Map (start of your registry)

Note: Canada Post only ships within Canada and to the US/International. FedEx and ShipHawk are global.

Quick Reference: Where Each Carrier Is Different

Checklist prepared for: Multi-Carrier Shipping Aggregator Technical Discovery Carriers covered: FedEx REST API · ShipHawk API v4 · Canada Post REST API