API Reference

API Documentation

The MesColis API gives B2B customers programmatic access to carrier rates, shipment creation, pickup scheduling, and package tracking. All endpoints return JSON.

Base URL: https://mescolis.ca/api | Support: support@mescolis.ca

Authentication

All API requests require a Bearer token in the Authorization header. Obtain your API key from the MesColis admin panel under Settings → API Keys.

Authorization: Bearer mc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are prefixed with mc_live_ for production and mc_test_ for sandbox. Never expose your API key in client-side code.

Rate Limits

All endpoints are rate-limited per API key using a sliding window algorithm. Exceeding the limit returns HTTP 429 Too Many Requests with aRetry-After header.

Endpoint	Limit	Window
POST /api/shipping/rates	60 requests	1 minute
POST /api/shipping/shipments	20 requests	1 minute
GET /api/shipments/track/*	120 requests	1 minute
GET /api/pickups	60 requests	1 minute
POST /api/pickups	20 requests	1 hour

Endpoints

GET/api/carriers

Returns the list of available carriers and their configuration status.

Response

{
  "carriers": [
    {
      "id": "canada_post",
      "name": "Canada Post",
      "enabled": true,
      "services": ["Expedited Parcel", "Xpresspost", "Priority"]
    },
    {
      "id": "ups",
      "name": "UPS",
      "enabled": true,
      "services": ["UPS Standard", "UPS Expedited", "UPS Express"]
    },
    {
      "id": "fedex",
      "name": "FedEx",
      "enabled": true,
      "services": ["FedEx Ground", "FedEx Express Saver", "FedEx Priority Overnight"]
    },
    {
      "id": "purolator",
      "name": "Purolator",
      "enabled": true,
      "services": ["Purolator Ground", "Purolator Express"]
    },
    {
      "id": "dhl",
      "name": "DHL Express",
      "enabled": true,
      "services": ["DHL Express Worldwide", "DHL Express 12:00"]
    }
  ]
}

POST/api/shipping/rates

Compare carrier rates for a shipment. Returns all available rates sorted by price.

Request Body

{
  "origin": {
    "country": "CA",
    "province": "QC",
    "postal_code": "H2X 1Y1",
    "city": "Montreal"
  },
  "destination": {
    "country": "CA",
    "province": "ON",
    "postal_code": "M5V 2T6",
    "city": "Toronto"
  },
  "parcel": {
    "weight_kg": 1.5,
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 15
  },
  "declared_currency": "CAD",
  "declared_customs_value": 50
}

Response

{
  "rates": [
    {
      "courier_id": "canada_post",
      "courier_name": "Canada Post",
      "service_name": "Expedited Parcel",
      "min_delivery_time": 2,
      "max_delivery_time": 3,
      "total_charge": 18.45,
      "currency": "CAD",
      "rate_id": "rate_abc123"
    }
  ]
}

POST/api/shipping/shipments

Create a shipment and purchase a shipping label. Returns label URL and tracking number.

Request Body

{
  "rate_id": "rate_abc123",
  "from": {
    "name": "Acme Inc.",
    "company": "Acme Inc.",
    "address": "123 Rue Principale",
    "city": "Montreal",
    "province": "QC",
    "postal_code": "H2X 1Y1",
    "country": "CA",
    "phone": "+15141234567",
    "email": "shipping@acme.ca"
  },
  "to": {
    "name": "Jane Smith",
    "address": "456 King Street W",
    "city": "Toronto",
    "province": "ON",
    "postal_code": "M5V 2T6",
    "country": "CA",
    "phone": "+14161234567",
    "email": "jane@example.com"
  },
  "parcel": {
    "weight_kg": 1.5,
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 15,
    "description": "Electronics accessories"
  },
  "payment_method_id": "pm_stripe_xxx"
}

Response

{
  "shipment": {
    "id": "SHP-ABC12345",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS",
    "service": "UPS Standard",
    "label_url": "https://mescolis.ca/api/labels/proxy?shipment_id=SHP-ABC12345",
    "status": "label_generated",
    "total_charged": 22.50,
    "currency": "CAD",
    "created_at": "2026-04-06T14:30:00Z"
  }
}

GET/api/shipments/track/[trackingNumber]

Get real-time tracking information for a shipment by tracking number.

Example Request

GET /api/shipments/track/1Z999AA10123456784

Response

{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "status": "In Transit",
  "last_update": "2026-04-06T10:15:00Z",
  "checkpoints": [
    {
      "message": "Package in transit to Toronto",
      "location": "Montreal, QC",
      "timestamp": "2026-04-06T08:30:00Z"
    }
  ],
  "estimated_delivery": "2026-04-08"
}

GET/api/pickups

Returns all scheduled pickups for the authenticated account.

Response

{
  "pickups": [
    {
      "id": "pickup_uuid",
      "carrier": "canada_post",
      "pickup_date": "2026-04-08",
      "pickup_time": "09:00–17:00",
      "address": "123 Rue Principale, Montreal QC H2X 1Y1",
      "packages": 3,
      "status": "scheduled",
      "created_at": "2026-04-06T14:00:00Z"
    }
  ]
}

POST/api/pickups

Schedule a carrier pickup at your address.

Request Body

{
  "carrier": "canada_post",
  "pickup_date": "2026-04-08",
  "pickup_time": "09:00–17:00",
  "address": "123 Rue Principale, Montreal QC H2X 1Y1",
  "packages": 3,
  "notes": "Leave at reception desk"
}

Response

{
  "pickup": {
    "id": "pickup_uuid",
    "carrier": "canada_post",
    "pickup_date": "2026-04-08",
    "pickup_time": "09:00–17:00",
    "status": "scheduled",
    "created_at": "2026-04-06T14:30:00Z"
  }
}

Error Codes

HTTP Status	Meaning
200 OK	Request succeeded
201 Created	Resource created (e.g. shipment, pickup)
400 Bad Request	Missing or invalid parameters — check error.message
401 Unauthorized	Missing or invalid API key
403 Forbidden	Action not permitted for this account
404 Not Found	Resource does not exist
429 Too Many Requests	Rate limit exceeded — check Retry-After header
500 Internal Server Error	Unexpected server error — contact support