API Documentation

Authentication

All API requests require an API token. You can find your token in the Developer tab of your Organization settings.

Include your token in one of two ways:

X-API-Key header

X-API-Key: your_api_token_here

Authorization header (Bearer token)

Authorization: Bearer your_api_token_here

Your API token identifies your organization. All shipments created via the API are billed to your organization's account.

Test Mode (Sandbox)

Test mode lets you develop and test your integration against the Weels API using real validation, real zone data, and real pricing — without dispatching shipments or being charged. It uses your same API token and the same endpoints. Shipments are stored in a separate test database so they never mix with live data.

This is useful for:

Realistic development — rates, validation errors, and labels all behave exactly like production. The only things skipped are dispatch, credit charges, and customer notifications.
Workflow validation — confirm that your system correctly handles success responses, parses tracking URLs, decodes labels, and processes errors before going live.
Team onboarding — let new developers experiment with the API freely without risk.

Enabling test mode

Toggle test mode on or off from the Developer tab in your Organization settings. When enabled, every API response will include a "test_mode": true field so your code can distinguish sandbox responses from live ones.

Remember to disable test mode before going live. It applies to all API calls made with your organization’s token. Shipments created from the Weels web dashboard are not affected.

Sandbox behaviour by endpoint

Endpoint	Sandbox Behaviour
`/api/shipment/rates`	Returns real zone rates with your organization’s discounts applied. Zone availability is checked against live data. Response includes `"test_mode": true`.
`/api/shipment/create`	Runs full validation and real pricing. The shipment is saved to `test_tasks` (not production). Real shipping labels are generated. No credit is deducted, no dispatch occurs, and no SMS is sent.
`/api/shipment/void`	Voids the test shipment in `test_tasks`. No credit refund or dispatch cancellation occurs.
`/api/shipment/label`	Returns a real shipping label generated from the test shipment data. All formats (PDF, ZPL, base64) are supported.

Example response

{
  "success": true,
  "test_mode": true,
  "task_id": 47,
  "total_price": 10.15,
  "tracking_url": "https://www.weels.ca/track/TEST-A1B2C3D4",
  "label_pdf": "JVBERi0xLjcK... (base64-encoded PDF)",
  "label_zpl": "^XA\\n^PW812\\n... (ZPL code)",
  "message": "Test mode: shipment created in test_tasks. No credit charged, no dispatch."
}

Check for "test_mode": true in responses to add conditional logic in your integration — for example, showing a sandbox banner in your UI or logging test shipments separately.

POST https://www.weels.ca/api/shipment/rates

Check if delivery is available at a postal code and get pricing. Use this to verify service availability and show estimated costs before creating a shipment.

Request Fields

Field	Type	Required	Options	Description
`postal`	string	Yes	—	Canadian postal code. Spaces are stripped automatically.
`age_verification`	integer	No	`0` `18` `19` `21`	Minimum age the recipient must verify upon delivery. `0` = none (default). Any other value adds a $1.00/pkg surcharge.
`signature`	boolean	No	`true` `false`	Require the recipient's signature upon delivery. Default: `false`. Adds a $1.00/pkg surcharge when enabled.
Packages — repeat with `[0]`, `[1]`, `[2]`... for multiple parcels
`packages[n][qty]`	integer	No	Default: `1`	Quantity of identical items in this parcel. Combined total across all parcels determines the volume discount tier (5% for 2, 10% for 3, 15% for 4+).

The packages[] array uses the same format as the Create Shipment endpoint. Only qty is used for rate calculation — weight and dimensions are not required. You can also pass a flat qty parameter instead if you only have one parcel.

Example Request

curl -X POST https://www.weels.ca/api/shipment/rates \
  -H "X-API-Key: your_api_token_here" \
  -d "postal=L6A1G2" \
  -d "packages[0][qty]=1" \
  -d "packages[1][qty]=2" \
  -d "signature=true"

$ch = curl_init('https://www.weels.ca/api/shipment/rates');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: your_api_token_here'],
    CURLOPT_POSTFIELDS     => http_build_query([
        'postal'    => 'L6A1G2',
        'packages'  => [['qty' => 1], ['qty' => 2]],
        'signature' => 'true',
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);

const res = await fetch('https://www.weels.ca/api/shipment/rates', {
    method: 'POST',
    headers: {
        'X-API-Key': 'your_api_token_here',
        'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
        postal: 'L6A1G2',
        'packages[0][qty]': '1',
        'packages[1][qty]': '2',
        signature: 'true',
    }),
});
const data = await res.json();

import requests

response = requests.post('https://www.weels.ca/api/shipment/rates', headers={
    'X-API-Key': 'your_api_token_here',
}, data={
    'postal': 'L6A1G2',
    'packages[0][qty]': '1',
    'packages[1][qty]': '2',
    'signature': 'true',
})
data = response.json()

Success Response (Available)

{
  "available": true,
  "city": "Maple",
  "province": "ON",
  "delivery_days": 1,
  "qty": 3,
  "rate": {
    "base_rate": 26.97,
    "surcharges": 3.00,
    "subtotal": 26.97,
    "tax_hst": 3.51,
    "total": 30.48
  }
}

Response (Not Available)

{
  "available": false,
  "postal": "V5K"
}

POST https://www.weels.ca/api/shipment/create

Create a new shipment. The recipient address is automatically verified. If address verification fails, the request is rejected with a descriptive error.

Request Fields

Field	Type	Required	Options	Description
Sender (Origin)
`origin_fname`	string	Yes	—	Sender first name
`origin_lname`	string	Yes	—	Sender last name
`origin_company`	string	No	—	Sender company or business name
`origin_phone`	string	No	—	Sender phone number (digits only, e.g. `4165551234`)
`origin_email`	string	No	—	Sender email address
`origin_address1`	string	Yes	—	Sender street address (e.g. `100 King St W`)
`origin_address2`	string	No	—	Sender unit, suite, or apartment number
`origin_city`	string	Yes	—	Sender city
`origin_province`	string	No	Default: `ON`	Sender province (2-letter code)
`origin_postalcode`	string	No	—	Sender postal code
`origin_country`	string	No	Default: `CA`	Sender country code (2-letter ISO)
Recipient (Destination)
`destination_fname`	string	Yes	—	Recipient first name
`destination_lname`	string	Yes	—	Recipient last name
`destination_company`	string	No	—	Recipient company or business name
`destination_phone`	string	Yes	—	Recipient phone number (digits only, e.g. `4165551234`)
`destination_email`	string	Yes	—	Recipient email address (used for delivery notifications)
`destination_address1`	string	Yes	—	Recipient street address. Verified automatically for accuracy.
`destination_address2`	string	No	—	Recipient unit, suite, or apartment number
`destination_city`	string	Yes	—	Recipient city
`destination_province`	string	No	Default: `ON`	Recipient province (2-letter code)
`destination_postalcode`	string	Yes	—	Recipient postal code. Must be within Weels delivery zones.
`destination_country`	string	No	Default: `CA`	Recipient country code (2-letter ISO)
Package Details — repeat with `[0]`, `[1]`, `[2]`... for multiple parcels
`packages[n][qty]`	integer	No	Default: `1`	Quantity of identical items in this parcel. Combined total across all parcels determines volume discount tier.
`packages[n][weight]`	decimal	Yes	—	Weight of the parcel in lbs (e.g. `2.5`)
`packages[n][width]`	decimal	Yes	—	Width of the parcel in inches
`packages[n][length]`	decimal	Yes	—	Length of the parcel in inches
`packages[n][height]`	decimal	Yes	—	Height of the parcel in inches
Shipment Options
`reference`	string	No	Max 100 chars	Your internal reference or tracking number. Displayed on the shipment label and included in webhooks.
`order_num`	string	No	Max 100 chars	Your order ID from your system (e.g. Shopify order number).
`notes`	string	No	Max 500 chars	Special delivery instructions for the courier (e.g. "Leave at side door", "Call on arrival").
`delivery_date`	string	Yes	Format: `YYYY-MM-DD`	Requested delivery date. Cannot be in the past. Must be a valid calendar date.
`age_verification`	integer	No	`0` `18` `19` `21`	Minimum age the recipient must verify at the door. `0` = none (default). Adds a $1.00/pkg surcharge when set.
`signature_required`	boolean	No	`true` `false`	Require the recipient's signature on delivery. Default: `false`. Adds a $1.00/pkg surcharge when enabled.

You can send multiple parcels by incrementing the array index: packages[0][...], packages[1][...], etc. Each parcel can have its own quantity and dimensions.

Example Request

curl -X POST https://www.weels.ca/api/shipment/create \
  -H "X-API-Key: your_api_token_here" \
  -d "origin_fname=John" \
  -d "origin_lname=Doe" \
  -d "origin_address1=100 King St W" \
  -d "origin_city=Toronto" \
  -d "destination_fname=Jane" \
  -d "destination_lname=Smith" \
  -d "destination_phone=4165551234" \
  -d "[email protected]" \
  -d "destination_address1=30 Pamela Crt" \
  -d "destination_city=Maple" \
  -d "destination_postalcode=L6A1G2" \
  -d "packages[0][qty]=1" \
  -d "packages[0][weight]=2.5" \
  -d "packages[0][width]=12" \
  -d "packages[0][length]=10" \
  -d "packages[0][height]=6" \
  -d "delivery_date=2026-02-15" \
  -d "order_num=ORD-12345" \
  -d "reference=REF-001"

$ch = curl_init('https://www.weels.ca/api/shipment/create');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: your_api_token_here'],
    CURLOPT_POSTFIELDS     => http_build_query([
        'origin_fname'           => 'John',
        'origin_lname'           => 'Doe',
        'origin_address1'        => '100 King St W',
        'origin_city'            => 'Toronto',
        'destination_fname'      => 'Jane',
        'destination_lname'      => 'Smith',
        'destination_phone'      => '4165551234',
        'destination_email'      => '[email protected]',
        'destination_address1'   => '30 Pamela Crt',
        'destination_city'       => 'Maple',
        'destination_postalcode' => 'L6A1G2',
        'packages' => [
            ['qty' => 1, 'weight' => 2.5, 'width' => 12, 'length' => 10, 'height' => 6],
        ],
        'delivery_date' => '2026-02-15',
        'order_num'     => 'ORD-12345',
        'reference'     => 'REF-001',
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);

const res = await fetch('https://www.weels.ca/api/shipment/create', {
    method: 'POST',
    headers: {
        'X-API-Key': 'your_api_token_here',
        'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
        origin_fname: 'John',
        origin_lname: 'Doe',
        origin_address1: '100 King St W',
        origin_city: 'Toronto',
        destination_fname: 'Jane',
        destination_lname: 'Smith',
        destination_phone: '4165551234',
        destination_email: '[email protected]',
        destination_address1: '30 Pamela Crt',
        destination_city: 'Maple',
        destination_postalcode: 'L6A1G2',
        'packages[0][qty]': '1',
        'packages[0][weight]': '2.5',
        'packages[0][width]': '12',
        'packages[0][length]': '10',
        'packages[0][height]': '6',
        delivery_date: '2026-02-15',
        order_num: 'ORD-12345',
        reference: 'REF-001',
    }),
});
const data = await res.json();

import requests

response = requests.post('https://www.weels.ca/api/shipment/create', headers={
    'X-API-Key': 'your_api_token_here',
}, data={
    'origin_fname': 'John',
    'origin_lname': 'Doe',
    'origin_address1': '100 King St W',
    'origin_city': 'Toronto',
    'destination_fname': 'Jane',
    'destination_lname': 'Smith',
    'destination_phone': '4165551234',
    'destination_email': '[email protected]',
    'destination_address1': '30 Pamela Crt',
    'destination_city': 'Maple',
    'destination_postalcode': 'L6A1G2',
    'packages[0][qty]': '1',
    'packages[0][weight]': '2.5',
    'packages[0][width]': '12',
    'packages[0][length]': '10',
    'packages[0][height]': '6',
    'delivery_date': '2026-02-15',
    'order_num': 'ORD-12345',
    'reference': 'REF-001',
})
data = response.json()

Success Response 200

{
  "success": true,
  "task_id": 142,
  "total_price": 10.15,
  "tracking_url": "https://www.weels.ca/track/abc123def",
  "label_pdf": "JVBERi0xLjcK... (base64-encoded PDF)",
  "label_zpl": "^XA\n^PW812\n... (ZPL code)",
  "message": "Shipment created successfully."
}

The response includes both label_pdf (base64-encoded 4x6" PDF) and label_zpl (ZPL code for thermal printers). Decode the PDF with base64 to save or print it. You can also retrieve labels later via the Get Label endpoint.

Error Responses

400 Validation Error

{
  "error": "Recipient first name is required. Recipient postal code is required."
}

400 Address Verification Failed

{
  "code": "address_verification_failed",
  "error": "The postal code doesn't match the address. Expected: L6A1G3.",
  "details": ["The postal code doesn't match the address. Expected: L6A1G3."]
}

402 Insufficient Credit (prepay accounts only)

{
  "code": "insufficient_credit",
  "error": "Insufficient balance.",
  "balance": 5.00,
  "required": 10.15,
  "shortfall": 5.15
}

POST https://www.weels.ca/api/shipment/void

Cancel a pending shipment that has not yet been picked up. Only shipments with a "Pending" status can be voided. For prepay accounts, the shipment cost is refunded to your credit balance.

Request Fields

Field	Type	Required	Options	Description
`task_id`	integer	Yes	—	The Weels shipment ID to void. Returned as `task_id` in the Create Shipment response.

Example Request

curl -X POST https://www.weels.ca/api/shipment/void \
  -H "X-API-Key: your_api_token_here" \
  -d "task_id=142"

$ch = curl_init('https://www.weels.ca/api/shipment/void');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: your_api_token_here'],
    CURLOPT_POSTFIELDS     => http_build_query(['task_id' => 142]),
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);

const res = await fetch('https://www.weels.ca/api/shipment/void', {
    method: 'POST',
    headers: {
        'X-API-Key': 'your_api_token_here',
        'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({ task_id: '142' }),
});
const data = await res.json();

import requests

response = requests.post('https://www.weels.ca/api/shipment/void', headers={
    'X-API-Key': 'your_api_token_here',
}, data={'task_id': '142'})
data = response.json()

Success Response 200

{
  "success": true,
  "message": "Shipment #142 has been voided.",
  "refunded": true,
  "refund_amount": 10.15
}

Error Responses

400 Not Voidable

{
  "error": "This shipment cannot be voided. Only pending shipments can be voided."
}

404 Not Found

{
  "error": "Shipment not found."
}

GET https://www.weels.ca/api/shipment/label

Retrieve a shipping label for a previously created shipment. Available as a PDF (for standard printers) or ZPL (for Zebra thermal printers).

Request Fields

Field	Type	Required	Options	Description
`task_id`	integer	Yes	—	The Weels shipment ID.
`format`	string	No	`pdf` `zpl` `pdf_base64`	Label format. `pdf` (default) streams the PDF inline. `zpl` returns raw ZPL text. `pdf_base64` returns JSON with base64-encoded PDF.

Example Request (PDF)

curl -H "X-API-Key: your_api_token_here" \
  "https://www.weels.ca/api/shipment/label?task_id=142&format=pdf" \
  --output label-142.pdf

$ch = curl_init('https://www.weels.ca/api/shipment/label?task_id=142&format=pdf');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: your_api_token_here'],
]);
$pdf = curl_exec($ch);
curl_close($ch);
file_put_contents('label-142.pdf', $pdf);

const res = await fetch('https://www.weels.ca/api/shipment/label?task_id=142&format=pdf', {
    headers: { 'X-API-Key': 'your_api_token_here' },
});
const buffer = await res.arrayBuffer();
require('fs').writeFileSync('label-142.pdf', Buffer.from(buffer));

import requests

response = requests.get('https://www.weels.ca/api/shipment/label', headers={
    'X-API-Key': 'your_api_token_here',
}, params={'task_id': 142, 'format': 'pdf'})

with open('label-142.pdf', 'wb') as f:
    f.write(response.content)

Example Request (ZPL)

curl -H "X-API-Key: your_api_token_here" \
  "https://www.weels.ca/api/shipment/label?task_id=142&format=zpl"

$ch = curl_init('https://www.weels.ca/api/shipment/label?task_id=142&format=zpl');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: your_api_token_here'],
]);
$zpl = curl_exec($ch);
curl_close($ch);

const res = await fetch('https://www.weels.ca/api/shipment/label?task_id=142&format=zpl', {
    headers: { 'X-API-Key': 'your_api_token_here' },
});
const zpl = await res.text();

import requests

response = requests.get('https://www.weels.ca/api/shipment/label', headers={
    'X-API-Key': 'your_api_token_here',
}, params={'task_id': 142, 'format': 'zpl'})
zpl = response.text

PDF Response

Returns the raw PDF binary with Content-Type: application/pdf. Open directly in a browser or save to file.

ZPL Response

Returns raw ZPL text with Content-Type: text/plain. Send directly to a Zebra thermal printer.

Base64 JSON Response

{
  "success": true,
  "task_id": 142,
  "label_pdf": "JVBERi0xLjcK... (base64-encoded PDF)"
}

POST https://www.weels.ca/api/shipment/change

Reschedule the delivery date for an active shipment. Only shipments with status 0 (Label Created), 1 (At Sorting Facility), or 2 (With Courier) can be rescheduled. Optionally sends an SMS notification to the recipient.

Request Fields

Field	Type	Required	Options	Description
`task_id`	integer	Yes	—	The Weels shipment ID to reschedule.
`delivery_date`	string	Yes	Format: `YYYY-MM-DD`	The new delivery date.
`notify_customer`	boolean	No	`true` `false`	Send an SMS to the recipient about the date change. Default: `false`.

Example Request

curl -X POST https://www.weels.ca/api/shipment/change \
  -H "X-API-Key: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{"task_id": 142, "delivery_date": "2026-03-01", "notify_customer": true}'

$ch = curl_init('https://www.weels.ca/api/shipment/change');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: your_api_token_here',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'task_id'         => 142,
        'delivery_date'   => '2026-03-01',
        'notify_customer' => true,
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);

const res = await fetch('https://www.weels.ca/api/shipment/change', {
    method: 'POST',
    headers: {
        'X-API-Key': 'your_api_token_here',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        task_id: 142,
        delivery_date: '2026-03-01',
        notify_customer: true,
    }),
});
const data = await res.json();

import requests

response = requests.post('https://www.weels.ca/api/shipment/change', headers={
    'X-API-Key': 'your_api_token_here',
}, json={
    'task_id': 142,
    'delivery_date': '2026-03-01',
    'notify_customer': True,
})
data = response.json()

Success Response 200

{
  "success": true,
  "task_id": 142,
  "delivery_date": "2026-03-01",
  "old_date": "2026-02-15",
  "message": "Delivery date updated successfully.",
  "sms_sent": true
}

Error Responses

400 Not Modifiable

{
  "error": "This shipment can no longer be modified. Only pending or in-progress shipments can be rescheduled."
}

404 Not Found

{
  "error": "Shipment not found."
}

GET https://www.weels.ca/api/drivers/{mm/dd/yyyy}

List all drivers and their assigned packages for a specific delivery date. Only includes shipments with status 0, 1, or 2 (active, pre-delivery). If no date is provided, defaults to today.

URL Parameters

Parameter	Type	Required	Description
`{mm/dd/yyyy}`	string	No	Delivery date in `mm/dd/yyyy` format. Defaults to today if omitted.

Example Request

curl -H "X-API-Key: your_api_token_here" \
  "https://www.weels.ca/api/drivers/02/18/2026"

$ch = curl_init('https://www.weels.ca/api/drivers/02/18/2026');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: your_api_token_here'],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);

const res = await fetch('https://www.weels.ca/api/drivers/02/18/2026', {
    headers: { 'X-API-Key': 'your_api_token_here' },
});
const data = await res.json();

import requests

response = requests.get('https://www.weels.ca/api/drivers/02/18/2026', headers={
    'X-API-Key': 'your_api_token_here',
})
data = response.json()

Success Response 200

{
  "drivers": [
    {
      "name": "John Smith",
      "packages": [
        {
          "reference": "REF-001",
          "shipment_id": 142,
          "status": 1,
          "confirmed": 0,
          "order_num": "ORD-12345",
          "name": "Jane Doe"
        }
      ]
    },
    {
      "name": "Unassigned",
      "packages": [
        {
          "reference": "REF-002",
          "shipment_id": 143,
          "status": 0,
          "confirmed": 0,
          "order_num": "ORD-12346",
          "name": "Bob Wilson"
        }
      ]
    }
  ]
}

Packages not yet assigned to a driver are grouped under the "Unassigned" driver entry. The confirmed field is 1 if the delivery has been completed, 0 otherwise.

GET https://www.weels.ca/api/cities

Returns a list of distinct city names within the Weels delivery network. This endpoint is public and does not require authentication.

Example Request

curl "https://www.weels.ca/api/cities"

$response = file_get_contents('https://www.weels.ca/api/cities');
$data = json_decode($response, true);

const res = await fetch('https://www.weels.ca/api/cities');
const data = await res.json();

import requests

response = requests.get('https://www.weels.ca/api/cities')
data = response.json()

Success Response 200

[
  { "name": "Ajax" },
  { "name": "Aurora" },
  { "name": "Brampton" },
  { "name": "Etobicoke" },
  { "name": "Maple" },
  { "name": "Markham" },
  { "name": "Mississauga" },
  { "name": "Toronto" }
]

The response is a flat JSON array of city objects. Cities are sorted alphabetically and returned with title-cased names. Results are cached for one hour.

GET https://www.weels.ca/api/days

Returns the available delivery days for a postal code. Uses longest-prefix matching to find the most specific zone. This endpoint is public and does not require authentication.

Request Fields

Field	Type	Required	Options	Description
`postal`	string	Yes	—	Canadian postal code (at least the 3-character FSA). Spaces and special characters are stripped automatically.

Example Request

curl "https://www.weels.ca/api/days?postal=L6A1G2"

$response = file_get_contents('https://www.weels.ca/api/days?postal=L6A1G2');
$data = json_decode($response, true);

const res = await fetch('https://www.weels.ca/api/days?postal=L6A1G2');
const data = await res.json();

import requests

response = requests.get('https://www.weels.ca/api/days', params={
    'postal': 'L6A1G2',
})
data = response.json()

Success Response (Covered) 200

{
  "success": true,
  "covered": true,
  "days": ["Saturday", "Sunday", "Monday", "Tuesday", "Wednesday"],
  "dday": "Saturday,Sunday,Monday,Tuesday,Wednesday"
}

Response (Not Covered) 200

{
  "success": false,
  "covered": false
}

Error Responses

400 Invalid Postal Code

{
  "error": "Postal code must be at least 3 characters."
}

The days array contains full day names. The dday field provides the same data as a comma-separated string for convenience. If a zone is found but has no delivery days configured, defaults to Saturday through Wednesday.

GET https://www.weels.ca/api/blackouts

Returns all active, future blackout dates — days when deliveries are not available, labels cannot be created, and rate ETAs are adjusted. Each entry includes a preferred date (the next available delivery day after the blackout) for use in scheduling.

Example Request

curl -H "X-API-Key: your_api_token_here" \
  "https://www.weels.ca/api/blackouts"

$ch = curl_init('https://www.weels.ca/api/blackouts');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: your_api_token_here'],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);

const res = await fetch('https://www.weels.ca/api/blackouts', {
    headers: { 'X-API-Key': 'your_api_token_here' },
});
const data = await res.json();

import requests

response = requests.get('https://www.weels.ca/api/blackouts', headers={
    'X-API-Key': 'your_api_token_here',
})
data = response.json()

Success Response 200

{
  "success": true,
  "blackouts": [
    {
      "date": "2026-04-03",
      "description": "Good Friday",
      "recurring": 0,
      "preferred": "2026-04-04"
    },
    {
      "date": "2026-07-01",
      "description": "Canada Day",
      "recurring": 1,
      "preferred": "2026-07-02"
    },
    {
      "date": "2026-12-25",
      "description": "Christmas Day",
      "recurring": 1,
      "preferred": "2026-12-27"
    }
  ]
}

Response Fields

Field	Type	Description
`date`	string	The blackout date (`YYYY-MM-DD`). For recurring dates, projected to the current or next year.
`description`	string\|null	Human-readable label (e.g. "Christmas Day").
`recurring`	integer	`1` if the blackout repeats every year, `0` if one-time.
`preferred`	string	The next available delivery day after the blackout (`YYYY-MM-DD`). Skips consecutive blackout dates.

Use the preferred date to adjust ETAs when a delivery would land on a blackout date. If multiple blackout dates are consecutive (e.g. Dec 25 & 26), preferred will be the first available day after all of them. Only active, future blackout dates are returned. Recurring dates are automatically projected to the current or next year.

Error Handling

All errors return a JSON object with an error field. Some errors also include a code field for programmatic handling.

HTTP Code	Meaning
`400`	Bad Request -- validation errors, invalid input, address verification failed
`401`	Unauthorized -- invalid or missing API token
`402`	Payment Required -- insufficient credit balance (prepay accounts)
`403`	Forbidden -- token valid but not authorized for this resource
`404`	Not Found -- shipment does not exist
`405`	Method Not Allowed -- wrong HTTP method
`429`	Too Many Requests -- rate limit exceeded
`502`	Bad Gateway -- delivery service error

Shipment Statuses

Each shipment has a numeric status code. These are the possible values:

Code	Label
`0`	Delivery label has been created
`1`	Package received at sorting facility
`2`	Package is with courier
`3`	Out for delivery
`4`	Delivered
`5`	Delivery label has been cancelled
`6`	Failed to deliver
`7`	Package picked up from vendor
`8`	New shipment created
`9`	Package en route to transfer hub
`10`	Package held after failed delivery
`11`	Package reported lost — insurance claim filed

Webhooks

Webhooks let Weels push real-time event notifications to your server when task statuses change — no polling required. You register an HTTPS endpoint and choose which events to subscribe to. Weels sends a signed POST request to your URL whenever a matching event occurs.

Webhooks are managed from the Developer tab of your Organization settings. Your endpoint must be publicly reachable and return a 2xx response — this is verified at registration time.

Events

Event	Fired when
`task.shipped`	A shipment is created and assigned to a delivery date
`task.started`	A driver starts a delivery or pickup
`task.arrived`	The driver marks arrival at the destination
`task.completed`	The delivery or pickup is successfully completed
`task.failed`	The delivery or pickup attempt was unsuccessful

Payload

Every webhook request is an HTTP POST with a Content-Type: application/json body in the following shape:

{
  "event": "task.completed",
  "timestamp": "2026-02-20T14:32:00-05:00",
  "data": {
    "task_id": 48291,
    "order_num": "WLS-10042",
    "task_type": "delivery",
    "status": 4,
    "driver": "Sam B.",
    "tracking": "https://www.weels.ca/track/48291",
    "destination": {
      "name": "Jane Smith",
      "address": "123 King St W, Toronto, ON M5H 1J9"
    },
    "started_at": "2026-02-20T13:58:00-05:00",
    "completed_at": "2026-02-20T14:32:00-05:00"
  }
}

Payload Fields

Field	Type	Description
`event`	string	The event name (see Events above)
`timestamp`	string	ISO 8601 datetime when the event was fired
`data.task_id`	integer	Internal Weels task ID
`data.order_num`	string\|null	Your order/reference number as submitted
`data.task_type`	string	`delivery` or `pickup`
`data.status`	integer	Numeric task status code (see Shipment Statuses)
`data.driver`	string\|null	Driver's first name and last initial (e.g. `Sam B.`)
`data.tracking`	string	Public tracking page URL
`data.destination.name`	string	Recipient full name
`data.destination.address`	string	Full destination address
`data.started_at`	string\|null	ISO 8601 datetime when the driver started the task
`data.completed_at`	string\|null	ISO 8601 datetime when the task was completed

Verifying Signatures

Every request includes an X-Weels-Signature header. Verify it before processing the payload to confirm the request came from Weels and hasn't been tampered with.

Where is my signing secret? When you register a webhook under Organization Settings → Developer → Webhooks, the signing secret is displayed once immediately after creation. Copy it and store it securely in your environment variables — it cannot be retrieved again. If you lose it, delete the webhook and create a new one.

The signature is an HMAC-SHA256 of <timestamp>.<raw_body>, keyed with your secret. Both the signature and timestamp are sent as headers:

X-Weels-Signature:  sha256=<HMAC-SHA256(timestamp + "." + raw_body, secret)>
X-Weels-Timestamp:  1740000000

To verify, reconstruct the signed content from the timestamp header and the raw body, then compare signatures. Reject payloads older than 5 minutes to prevent replay attacks:

$payload   = file_get_contents('php://input');
$secret    = 'your_webhook_secret';
$timestamp = $_SERVER['HTTP_X_WEELS_TIMESTAMP'] ?? '';
$received  = $_SERVER['HTTP_X_WEELS_SIGNATURE'] ?? '';

// Reject payloads older than 5 minutes
if (abs(time() - (int)$timestamp) > 300) {
    http_response_code(401);
    exit('Timestamp too old');
}

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($payload, true);
// process $event...

const crypto = require('crypto');

app.post('/webhooks/weels', (req, res) => {
    const payload   = req.rawBody; // must be raw Buffer/string
    const secret    = 'your_webhook_secret';
    const timestamp = req.headers['x-weels-timestamp'] || '';
    const received  = req.headers['x-weels-signature'] || '';

    // Reject payloads older than 5 minutes
    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
        return res.status(401).send('Timestamp too old');
    }

    const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(timestamp + '.' + payload)
        .digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
        return res.status(401).send('Invalid signature');
    }

    const event = req.body;
    // process event...
    res.sendStatus(200);
});

import hmac, hashlib, time
from flask import request, abort

@app.route('/webhooks/weels', methods=['POST'])
def webhook():
    payload   = request.get_data()
    secret    = b'your_webhook_secret'
    timestamp = request.headers.get('X-Weels-Timestamp', '')
    received  = request.headers.get('X-Weels-Signature', '')

    # Reject payloads older than 5 minutes
    if abs(time.time() - int(timestamp or 0)) > 300:
        abort(401)

    signed = timestamp.encode() + b'.' + payload
    expected = 'sha256=' + hmac.new(secret, signed, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, received):
        abort(401)

    event = request.get_json()
    # process event...
    return '', 200

Request Headers

Header	Value
`Content-Type`	`application/json`
`X-Weels-Event`	The event name (e.g. `task.completed`)
`X-Weels-Signature`	HMAC-SHA256 signature of `timestamp.body`, prefixed with `sha256=`
`X-Weels-Timestamp`	Unix timestamp (seconds) when the request was signed — use for replay protection
`User-Agent`	`Weels-Webhook/1.0`

Reliability & Auto-Disable

Weels expects your endpoint to respond with a 2xx status within 10 seconds. Any other response (including timeouts) is considered a failure.
After 5 consecutive delivery failures, the webhook is automatically disabled to prevent unnecessary traffic to a broken endpoint.
You'll see the webhook marked as Failed in your Developer settings. Fix your endpoint, then re-enable it — the failure counter resets automatically on the next successful delivery.
Use the Test button in your Developer settings to send a webhook.test ping and confirm your endpoint is reachable at any time.

Your endpoint must respond quickly. Do not perform heavy processing synchronously — acknowledge the webhook with a 200 immediately and handle processing in a background job.