API reference

Rates

Live quotes from every carrier, checkout totals and drop-off locations.

Endpoints

POST /rates
GET /rates/dropoffs
POST /rates/quick
GET /shipments/duties-availability
POST /shipments/price-preview

Get rates

POST /v1/rates

Live quotes from every carrier the account can use, cheapest first, with delivery estimates. The response has a quote_id; pass it when you buy so the purchase is linked to the quote. For a shipment that crosses a border, create a customs declaration first and pass customs_declaration_id so carriers can quote duties and international services. Nothing is charged.

Request body

from • Required object

Ship-from address.
Fields · 11
- city • Required string
  
  City.
- country • Required string
  
  Two-letter country code, e.g. CA, US.
- name • Required string
- postal_code • Required string
  
  Postal or ZIP code.
- state • Required string
  
  Province or state code, e.g. ON, BC, NY.
- street • Required string
  
  Street address.
- company string
  
  Company name.
- email string
  
  Email address.
- is_residential boolean
  
  True for a home address. Some carriers charge more for residential delivery.
- line2 string
  
  Apartment, suite or unit.
- phone string
  
  Phone number. Carriers need one for the recipient on most international and express services.
packages • Required array of objects

One entry per box.
Each item · 6
- dimension_unit • Required string
  
  in or cm.
- height • Required number
  
  Height, in dimension_unit.
- length • Required number
  
  Length, in dimension_unit.
- weight • Required number
  
  Weight of the box with its contents, in weight_unit.
- weight_unit • Required string
  
  lb or kg.
- width • Required number
  
  Width, in dimension_unit.
to • Required object

Ship-to address.
Fields · 11
- city • Required string
  
  City.
- country • Required string
  
  Two-letter country code, e.g. CA, US.
- name • Required string
- postal_code • Required string
  
  Postal or ZIP code.
- state • Required string
  
  Province or state code, e.g. ON, BC, NY.
- street • Required string
  
  Street address.
- company string
  
  Company name.
- email string
  
  Email address.
- is_residential boolean
  
  True for a home address. Some carriers charge more for residential delivery.
- line2 string
  
  Apartment, suite or unit.
- phone string
  
  Phone number. Carriers need one for the recipient on most international and express services.
carriers array of strings

Only return rates from these carriers, e.g. ["canada_post"] or ["gls", "canpar"]. Codes: canada_post, ups, fedex, purolator, canpar, gls, uniuni, dhl_express. Leave it out for every carrier.
currency string

Three-letter currency code, e.g. CAD.
customs_declaration_id uuid

A customs declaration from POST /v1/customs/declarations. Needed for shipments that cross a border.
ship_date date

Day the parcel will be handed to the carrier (YYYY-MM-DD). Leave out for today; up to 7 days ahead.
signature_option string

Signature on delivery: none, required or adult. Carriers charge extra for a signature.

Response in `data`

items • Required array of objects
Each item · 18
- adult_signature_supported • Required boolean
  
  False when the carrier has no adult signature option; adult becomes required.
- amount_cents • Required integer
  
  Amount in cents.
- carrier • Required string
  
  The carrier that delivers the parcel, e.g. canada_post, ups, purolator.
- carrier_display_name • Required string
  
  The carrier's name to show, e.g. "Canada Post".
- currency • Required string
  
  Three-letter currency code, e.g. CAD.
- service_code • Required string
  
  Service code, as returned with each rate. Treat it as opaque and send it back unchanged when you buy: it can carry routing details for that exact rate.
- service_name • Required string
  
  Service name to show to people.
- carrier_description string
- carrier_logo_url string
- duties_cents integer
  
  Destination duties and taxes prepaid with this label (DDP), when offered.
- estimated_days integer
  
  Estimated business days in transit.
- estimated_delivery timestamp
  
  Estimated delivery date and time.
- pickup_supported boolean
  
  False when the carrier cannot pick this parcel up: drop it off instead.
- promotion boolean
  
  True for a discounted promotional rate shown without carrier branding.
- published_cents integer
  
  The carrier's own list price for this service, when the carrier publishes one.
- service_description string
- service_logo_url string
- tracking_available boolean
  
  False for a service without tracking.
carriers_with_no_options array of objects
Each item · 3
- carrier • Required string
  
  Carrier code, as returned with each rate.
- carrier_display_name • Required string
  
  Carrier name to show to people.
- reason • Required string
quote_id uuid

The quote_id from the POST /v1/rates response the chosen rate came from.

POST /v1/rates

curl -X POST "https://api.parcelhub.ca/v1/rates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "carriers": [
    "ups"
  ],
  "currency": "CAD",
  "from": {
    "city": "Toronto",
    "company": "Maple Goods Inc.",
    "country": "CA",
    "email": "[email protected]",
    "is_residential": false,
    "line2": "Suite 400",
    "name": "Alex Martin",
    "phone": "+1 416 555 0100",
    "postal_code": "M5V 2T6",
    "state": "ON",
    "street": "123 King St W"
  },
  "packages": [
    {
      "dimension_unit": "cm",
      "height": 10,
      "length": 30,
      "weight": 2.5,
      "weight_unit": "kg",
      "width": 20
    }
  ],
  "ship_date": "2026-11-03",
  "signature_option": "none",
  "to": {
    "city": "Toronto",
    "company": "Maple Goods Inc.",
    "country": "CA",
    "email": "[email protected]",
    "is_residential": false,
    "line2": "Suite 400",
    "name": "Alex Martin",
    "phone": "+1 416 555 0100",
    "postal_code": "M5V 2T6",
    "state": "ON",
    "street": "123 King St W"
  }
}'

Response

{
  "ok": true,
  "data": {
    "carriers_with_no_options": [
      {
        "carrier": "ups",
        "carrier_display_name": "UPS",
        "reason": "string"
      }
    ],
    "items": [
      {
        "adult_signature_supported": true,
        "amount_cents": 1299,
        "carrier": "ups",
        "carrier_description": "string",
        "carrier_display_name": "UPS",
        "carrier_logo_url": "https://…",
        "currency": "CAD",
        "duties_cents": 1299,
        "estimated_days": 3,
        "estimated_delivery": "2026-10-31T15:04:05Z",
        "pickup_supported": true,
        "promotion": true,
        "published_cents": 1299,
        "service_code": "string",
        "service_description": "string",
        "service_logo_url": "https://…",
        "service_name": "UPS Standard",
        "tracking_available": true
      }
    ],
    "quote_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
  },
  "request_id": "01JBX7Q2…"
}

Find drop-off locations

GET /v1/rates/dropoffs

The nearest carrier drop-off points (post offices, UPS, FedEx, Purolator and other counters) around an address, by carrier, with distance and opening hours where known.

Query parameters

address • Required string

The address to search around, usually the ship-from address.
carriers string

Comma-separated carrier codes, e.g. canada_post,ups. Leave out for all.
radiusKm number

Search radius in kilometres.
limit integer

Most results to return.

Response in `data`

See the example on the right.

GET /v1/rates/dropoffs

1
2

curl "https://api.parcelhub.ca/v1/rates/dropoffs?address=123%20King%20St%20W%2C%20Toronto%20ON" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": null,
  "request_id": "01JBX7Q2…"
}

Quick estimate

POST /v1/rates/quick

A faster, lighter estimate across carriers, for showing a price before all details are known. Use POST /v1/rates before buying. Nothing is charged.

Request body

from • Required object

Ship-from address.
Fields · 11
- city • Required string
  
  City.
- country • Required string
  
  Two-letter country code, e.g. CA, US.
- name • Required string
- postal_code • Required string
  
  Postal or ZIP code.
- state • Required string
  
  Province or state code, e.g. ON, BC, NY.
- street • Required string
  
  Street address.
- company string
  
  Company name.
- email string
  
  Email address.
- is_residential boolean
  
  True for a home address. Some carriers charge more for residential delivery.
- line2 string
  
  Apartment, suite or unit.
- phone string
  
  Phone number. Carriers need one for the recipient on most international and express services.
packages • Required array of objects

One entry per box.
Each item · 6
- dimension_unit • Required string
  
  in or cm.
- height • Required number
  
  Height, in dimension_unit.
- length • Required number
  
  Length, in dimension_unit.
- weight • Required number
  
  Weight of the box with its contents, in weight_unit.
- weight_unit • Required string
  
  lb or kg.
- width • Required number
  
  Width, in dimension_unit.
to • Required object

Ship-to address.
Fields · 11
- city • Required string
  
  City.
- country • Required string
  
  Two-letter country code, e.g. CA, US.
- name • Required string
- postal_code • Required string
  
  Postal or ZIP code.
- state • Required string
  
  Province or state code, e.g. ON, BC, NY.
- street • Required string
  
  Street address.
- company string
  
  Company name.
- email string
  
  Email address.
- is_residential boolean
  
  True for a home address. Some carriers charge more for residential delivery.
- line2 string
  
  Apartment, suite or unit.
- phone string
  
  Phone number. Carriers need one for the recipient on most international and express services.
carriers array of strings

Only return rates from these carriers, e.g. ["canada_post"] or ["gls", "canpar"]. Codes: canada_post, ups, fedex, purolator, canpar, gls, uniuni, dhl_express. Leave it out for every carrier.
currency string

Three-letter currency code, e.g. CAD.
customs_declaration_id uuid

A customs declaration from POST /v1/customs/declarations. Needed for shipments that cross a border.
ship_date date

Day the parcel will be handed to the carrier (YYYY-MM-DD). Leave out for today; up to 7 days ahead.
signature_option string

Signature on delivery: none, required or adult. Carriers charge extra for a signature.

Response in `data`

items • Required array of objects
Each item · 18
- adult_signature_supported • Required boolean
  
  False when the carrier has no adult signature option; adult becomes required.
- amount_cents • Required integer
  
  Amount in cents.
- carrier • Required string
  
  The carrier that delivers the parcel, e.g. canada_post, ups, purolator.
- carrier_display_name • Required string
  
  The carrier's name to show, e.g. "Canada Post".
- currency • Required string
  
  Three-letter currency code, e.g. CAD.
- service_code • Required string
  
  Service code, as returned with each rate. Treat it as opaque and send it back unchanged when you buy: it can carry routing details for that exact rate.
- service_name • Required string
  
  Service name to show to people.
- carrier_description string
- carrier_logo_url string
- duties_cents integer
  
  Destination duties and taxes prepaid with this label (DDP), when offered.
- estimated_days integer
  
  Estimated business days in transit.
- estimated_delivery timestamp
  
  Estimated delivery date and time.
- pickup_supported boolean
  
  False when the carrier cannot pick this parcel up: drop it off instead.
- promotion boolean
  
  True for a discounted promotional rate shown without carrier branding.
- published_cents integer
  
  The carrier's own list price for this service, when the carrier publishes one.
- service_description string
- service_logo_url string
- tracking_available boolean
  
  False for a service without tracking.
carriers_with_no_options array of objects
Each item · 3
- carrier • Required string
  
  Carrier code, as returned with each rate.
- carrier_display_name • Required string
  
  Carrier name to show to people.
- reason • Required string
quote_id uuid

The quote_id from the POST /v1/rates response the chosen rate came from.

POST /v1/rates/quick

curl -X POST "https://api.parcelhub.ca/v1/rates/quick" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "carriers": [
    "ups"
  ],
  "currency": "CAD",
  "from": {
    "city": "Toronto",
    "company": "Maple Goods Inc.",
    "country": "CA",
    "email": "[email protected]",
    "is_residential": false,
    "line2": "Suite 400",
    "name": "Alex Martin",
    "phone": "+1 416 555 0100",
    "postal_code": "M5V 2T6",
    "state": "ON",
    "street": "123 King St W"
  },
  "packages": [
    {
      "dimension_unit": "cm",
      "height": 10,
      "length": 30,
      "weight": 2.5,
      "weight_unit": "kg",
      "width": 20
    }
  ],
  "ship_date": "2026-11-03",
  "signature_option": "none",
  "to": {
    "city": "Toronto",
    "company": "Maple Goods Inc.",
    "country": "CA",
    "email": "[email protected]",
    "is_residential": false,
    "line2": "Suite 400",
    "name": "Alex Martin",
    "phone": "+1 416 555 0100",
    "postal_code": "M5V 2T6",
    "state": "ON",
    "street": "123 King St W"
  }
}'

Response

{
  "ok": true,
  "data": {
    "carriers_with_no_options": [
      {
        "carrier": "ups",
        "carrier_display_name": "UPS",
        "reason": "string"
      }
    ],
    "items": [
      {
        "adult_signature_supported": true,
        "amount_cents": 1299,
        "carrier": "ups",
        "carrier_description": "string",
        "carrier_display_name": "UPS",
        "carrier_logo_url": "https://…",
        "currency": "CAD",
        "duties_cents": 1299,
        "estimated_days": 3,
        "estimated_delivery": "2026-10-31T15:04:05Z",
        "pickup_supported": true,
        "promotion": true,
        "published_cents": 1299,
        "service_code": "string",
        "service_description": "string",
        "service_logo_url": "https://…",
        "service_name": "UPS Standard",
        "tracking_available": true
      }
    ],
    "quote_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
  },
  "request_id": "01JBX7Q2…"
}

Prepaid duties availability

GET /v1/shipments/duties-availability

Whether prepaid duties and taxes (DDP: the recipient pays nothing on delivery) are offered right now, for US-bound parcels and for other countries.

Response in `data`

international • Required boolean
us • Required boolean

GET /v1/shipments/duties-availability

1
2

curl "https://api.parcelhub.ca/v1/shipments/duties-availability" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": {
    "international": true,
    "us": true
  },
  "request_id": "01JBX7Q2…"
}

Checkout total

POST /v1/shipments/price-preview

The exact total for a chosen rate: sales tax for the route, any discount (a code you pass, or the best promotion already claimed on the account) and prepaid duties. Nothing is charged.

Request body

amount_cents • Required integer

The chosen rate's price before tax, in cents.
from_country • Required string

Ship-from country code.
to_country • Required string

Ship-to country code.
discount_code string

A discount code to apply.
duties_cents integer

The chosen rate's prepaid duties (duties_cents on the rate), if any.
to_state string

Destination province or state: Canadian sales tax follows it.

Response in `data`

discount_cents • Required integer

Discount applied, in cents.
duties_cents • Required integer

Destination duties and taxes prepaid with this label (DDP), when offered.
subtotal_cents • Required integer
system_paid • Required boolean
tax_cents • Required integer

Sales tax, in cents.
tax_lines • Required array of objects
Each item · 3
- amount_cents • Required integer
  
  Amount in cents.
- rate_bps • Required integer
- tax_type • Required string
tax_rate_bps • Required integer
total_cents • Required integer

Total, in cents.
tax_region string

POST /v1/shipments/price-preview

curl -X POST "https://api.parcelhub.ca/v1/shipments/price-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_cents": 1299,
  "discount_code": "string",
  "duties_cents": 1299,
  "from_country": "string",
  "to_country": "string",
  "to_state": "string"
}'

Response

{
  "ok": true,
  "data": {
    "discount_cents": 1299,
    "duties_cents": 1299,
    "subtotal_cents": 1299,
    "system_paid": true,
    "tax_cents": 1299,
    "tax_lines": [
      {
        "amount_cents": 1299,
        "rate_bps": 1,
        "tax_type": "string"
      }
    ],
    "tax_rate_bps": 1,
    "tax_region": "string",
    "total_cents": 1299
  },
  "request_id": "01JBX7Q2…"
}

Rates

Get rates

Request body

Response in data

Find drop-off locations

Query parameters

Response in data

Quick estimate

Request body

Response in data

Prepaid duties availability

Response in data

Checkout total

Request body

Response in data

Response in `data`

Response in `data`

Response in `data`

Response in `data`

Response in `data`