POST /rate

Create a rate request, fetch carrier rates synchronously, and return sanitized rate responses. By default all quoted carriers are returned; use shippingType to narrow (see below).

Scope: shipments:rate

Request body

Validated by the apiRateRequest request schema.

Required top-level fields

Field	Type	Description
shippingOptions	object	Shipment options (see below)
shipper	object	Origin address
recipient	object	Destination address
packages	object	Package details

shippingOptions (required)

Field	Required	Type	Notes
shippingDate	Yes	string	ISO date, e.g. 2026-05-25 or 2026-05-25T14:00:00
shippingDateTimezone	No	string	Timezone for shipping date
references	No	object	customer, order, invoice strings
insurance	No	object	amount (number), currency (3-letter)
signature	No	string	none, required, adult
nonConveyable	No	boolean
createReturnLabel	No	boolean
saturdayDelivery	No	boolean
packingSlipType	No	string
deliveryInstructions	No	string

Address (shipper / recipient)

Field	Required	Type	Notes
personName	Yes	string
addressLine1	Yes	string
countryCode	Yes	string	2-letter ISO
provinceCode	No	string	2–4 chars
companyName, phoneNumber, emailAddress	No	string
addressLine2, city, provinceName, postalCode	No	string
residential	No	boolean
timezone, canadaPostId, id	No	string
type	No	string	shipping, broker, buyer

Nested objects use additionalProperties: false where defined in the schema.

packages (required)

Field	Required	Type	Notes
unitOfMeasure	Yes	string	imperial or metric
pieces	Yes	array	Min 1 piece

Each piece:

Field	Required	Type
quantity	Yes	number (≥ 1)
weight	Yes	number (≥ 0)
length	Yes	number (≥ 0)
width	Yes	number (≥ 0)
height	Yes	number (≥ 0)
packagingType	No	object
itemCount	No	number

Optional top-level fields

All optional blocks are defined in the apiRateRequest schema. The public API validates the body against that schema and passes each block through to carrier rating.

Unless noted, fields are passed through to every carrier that is quoted for the organization. Carriers ignore blocks they do not implement. Parcel examples below use FedEx (federal-express / mapRequest) and UPS Parcel (ups-parcel / rate/prepareRequest, ship/prepareRequest).

Field	Required for	Primary use
internationalOptions	Cross-border customs/duties	Customs clearance, duties payer, documents-only, declared value
freightOptions	LTL/freight carriers	Appointments, tailgate, two-person, after-hours (not parcel carriers)
commercialInvoice	International goods (non-documents)	Line items, HS codes, customs value for rating/shipping/labels
buyer	Some international / CI flows	Sold-to / buyer address (FedEx soldTo)
broker	Import broker selection	Customs broker (FedEx BROKER_SELECT_OPTION)
shippingNotificationOptions	Email on transit updates	Stored on quotation; UPS ship notification + tracker emails
billingOptions	Third-party billing	Restrict which carrier accounts are quoted; third-party ship at label time
shippingType	Controlling quote results (public API)	Filter bulk-rates output (default { "carrier": "all" })

---

internationalOptions

Customs and cross-border options. Most carriers only read this object when it is non-empty (FedEx builds customsClearanceDetail only if Object.keys(internationalOptions).length > 0). For international parcel rating you typically send internationalOptions together with commercialInvoice (goods) or documentsOnly: true (documents).

Field	Type	Schema	FedEx (mapRequest / customs)	UPS Parcel (rate / ship)	Other carriers
documentsOnly	boolean	optional	isDocumentOnly; commodities use fixed “Corporate Correspondence” lines	Rate: DocumentsOnlyIndicator + placeholder InvoiceLineTotal; ship: same + skips full commercial invoice forms	—
declaredValue	object	optional	Not mapped directly on rate (see commercialInvoice / package declared value)	Rate & ship: InvoiceLineTotal (value + currency) when set; overrides documents-only total	—
declaredValue.value	number	required if declaredValue present	—	Monetary value for invoice line total	—
declaredValue.currency	string	3-letter, required if declaredValue present	—	ISO currency on InvoiceLineTotal	—
billDutyTo	string	sender | recipient | thirdParty	Rate: duties payment SENDER when any intl options exist. Ship/validate: SENDER, RECIPIENT, or THIRD_PARTY (+ optional account)	Not mapped on UPS rate/ship in current code	DHL, Purolator Express, FedEx Freight (export purpose), etc.
dutyAccountNumber	string	optional	Required for meaningful THIRD_PARTY duties payor on ship	—	—
recipientTaxId	string	optional	Not referenced in carrier mappers today; stored on rate request	—	—
senderIsProducer	boolean	optional	Not referenced in carrier mappers today	—	—
businessRelationship	string	related | unrelated	Not referenced in FedEx mappers	—	Purolator Express, DHL Express, FedEx Freight
exportType	string	permanent | return | repair | returnRepair	Not referenced in FedEx parcel mappers	—	Purolator Express, DHL, FedEx Freight, generic CI PDF
brokerRequired	boolean	optional	Not referenced in FedEx parcel mappers	—	Day & Ross Freight REST
commercialInvoiceRequired	boolean	optional	Not referenced in carrier mappers today	—	—
postShipmentDocumentUpload	boolean	optional	Ship/validate: ELECTRONIC_TRADE_DOCUMENTS / post-upload ETD	—	—
requestEstimatedDutiesAndTaxes	boolean	optional	Adds FedEx edtRequestType: "ALL" on rate/ship customs block	—	—

Practical notes

• International vs domestic: UPS treats signature differently for international (shipment-level DeliveryConfirmation) vs domestic (package-level DeliveryConfirmation); see shippingOptions.signature and UPS signature / packages mappers.
• billDutyTo at rate time (FedEx): With any internationalOptions keys present, FedEx rate uses duties paymentType: "SENDER" regardless of billDutyTo; full duty billing follows on ship/validate.
• Schema: internationalOptions has additionalProperties: false — only the fields above are accepted by the public API.

---

freightOptions

LTL and freight carrier accessorials. Ignored by FedEx Parcel and UPS Parcel (those carriers error on shippingOptions.nonConveyable but do not read freightOptions). Used by freight carriers such as FedEx Freight, GLS Freight, Purolator Freight, Day & Ross, Day & Ross REST.

Field	Type	Values / shape	Carrier usage
appointment	string	free text	Delivery appointment note / call-before-delivery (e.g. FedEx Freight CALL_BEFORE_DELIVERY, GLS/Purolator BOL text)
prebookedAppointment	object	appointmentDate, appointmentTime (required)	Scheduled delivery window (FedEx Freight, GLS Freight, Day & Ross)
pickupAppointment	object	appointmentDate, appointmentTime (required)	Pickup window (Day & Ross / Day & Ross REST)
tailgate	string	pickup | delivery | both	Liftgate accessorials on rate/ship/BOL
twoPersons	string	pickup | delivery | both	Two-person handling (Purolator Freight BOL, etc.)
afterHours	string	pickup | delivery | both	After-hours pickup/delivery flags on labels/BOL

Practical notes

• Quote freight services only when the organization’s pricing plans include freight carriers; parcel-only requests can omit freightOptions.
• appointment is often combined with shippingOptions.deliveryInstructions on label/BOL output.

---

commercialInvoice

Commercial invoice / customs line-item data. Schema requires at least one invoiceItems entry when the object is present. Item-level template flags (selectedTemplateId, shouldSaveAsTemplate, shouldUpdateTemplate) are accepted by validation but are not used by the public API.

Field	Type	Schema	FedEx	UPS Parcel	Notes
generalNote	string | null	max 255	Stripped before rate worker	—	UI/note only for public API pipeline
customsValue	number	≥ 0	Mapped via totalCustomsValue when object present	Ship: part of intl value logic when no declaredValue	Total customs value
currency	string	3-letter	Commodity / customs currency	Invoice forms default CAD	Required for meaningful intl quotes
unitOfMeasure	string	imperial | metric	Commodity weight units	Invoice product weight LBS/KGS	Should align with packages.unitOfMeasure
buyerRequired	boolean	optional	Not referenced in FedEx parcel mappers	—	Accepted by schema; not used by the public API
invoiceItems	array	min 1 if object present	commodities (all items on rate/ship; first item only on validate)	Ship only: InternationalForms / Product list (rate does not send full CI)	See line item table below

invoiceItems[] line

Field	Required	FedEx commodity	UPS ship (InternationalForms)
description	Yes	name, description	Description
quantity	Yes	quantity	Unit.Number
value	Yes	unitPrice, customsValue (× qty)	Unit.Value
weight	Yes	weight per line	ProductWeight
hsCode	No	harmonizedCode	CommodityCode if non-empty
countryOfManufacture	No	countryOfManufacture	OriginCountryCode
unitOfMeasure	No	—	—

Practical notes

• Documents-only: Set internationalOptions.documentsOnly: true; FedEx synthesizes commodity lines; UPS uses documents indicator — commercialInvoice is usually omitted.
• Public API: The public schema does not include extra commercial-invoice fields supported elsewhere (e.g. UPS invoiceNumber, incoterm, freightCharges). Those are rejected by apiRateRequest validation (additionalProperties: false on commercialInvoice).
• Rate vs ship (UPS): Full InternationalForms are built at ship time from commercialInvoice; rate uses totals / declaredValue / documentsOnly only.

---

buyer

Optional party address (same field shape as shipper / recipient in schema: personName, addressLine1, countryCode, etc.; type may be shipping, broker, or buyer).

Carrier	Usage
FedEx	soldTo on requestedShipment via mapAddress(..., "buyer") on rate, ship, and validate
UPS Parcel	Not mapped to a dedicated buyer block; UPS ship InternationalForms SoldTo uses recipient contact today
Others	Passed through on rate request; carrier-specific

Send when FedEx or customs workflows require a distinct sold-to/importer distinct from recipient.

---

broker

Optional customs broker address (same address shape as buyer).

Carrier	Usage
FedEx	customsClearanceDetail.brokers (IMPORT broker from broker address); enables BROKER_SELECT_OPTION in shipmentSpecialServices when broker is non-empty
UPS Parcel	Not mapped in current UPS parcel code
Day & Ross Freight REST	internationalOptions.brokerRequired controls broker behavior (not the broker address block alone)

---

shippingNotificationOptions

Email notifications tied to the quotation. Applied asynchronously when shipment status changes (not during the synchronous rate call).

Field	Type	Schema	Behavior
shippingNotificationStatuses	string[]	pending, intransit, delivered, cancelled	UPS ship: when array includes intransit and email is set, adds UPS Notification on shipment create
shippingNotificationEmail	string	email	Tracker: when status becomes intransit and email is set, sends a status email

Practical notes

• Only intransit is wired end-to-end today for UPS ship + tracker emails.
• unsubscribe is not in the public API schema (additionalProperties: false on this object).

---

billingOptions

Not defined in apiRateRequest schema but allowed at the root of the JSON body (root schema has no additionalProperties: false).

Field	Type	When used
type	string	"thirdParty" triggers third-party billing flow
thirdPartyShipperNumber	string	Bill-to account number; must pass org blacklist rules unless featureFlags.allowBlacklistedThirdPartyBillingAccounts
carrierCode	string	With type: "thirdParty", limits quoting to that carrier’s pricing plans
soldTo	object (address)	UPS ship only: maps to UPS SoldTo (not validated by apiRateRequest)

Practical notes

• Third-party rates are flagged in FedEx/UPS/DHL/etc. processResponse when type === "thirdParty" and thirdPartyShipperNumber is set.
• Ship uses stored billingOptions from the rate request (public API ship does not accept billing in the body; org must be account billing).
• Blacklisted third-party accounts return 400 from rate validation when not allowed.

---

shippingType

Controls which quote(s) the public API returns after rating. Default when omitted: { "carrier": "all" } (every successful carrier quote).

carrier value	service	Result
(omit)	—	Treated as { "carrier": "all" }
all	ignored	Array of all carrier rates
cheapest	ignored	Single cheapest rate (by lowest total price)
fastest	ignored	Single rate with earliest commitment date/time
{carrierCode}	omitted	Cheapest rate for that carrier only (e.g. federal-express, ups-parcel)
any	{serviceCode}	First rate whose service.code matches service (case-insensitive) across all carriers
{carrierCode}	{serviceCode}	If service is set, selection is by service code only (the carrier filter is not applied)

Valid carrier codes for filtering include: federal-express, ups-parcel, purolator-express, canada-post, dhl-express, dhl-express-rest, canpar-express, day-ross-commerce, day-ross-freight, nationex, purolator-freight, gls-parcel, gls-freight, eshipper.

Example — all carriers (default):

{ "shippingType": { "carrier": "all" } }

Example — cheapest FedEx service only:

{ "shippingType": { "carrier": "federal-express" } }

Example — one service by code (any carrier that returns it):

{ "shippingType": { "carrier": "ups-parcel", "service": "11" } }

Practical notes

• shippingType affects which quotes are returned in the synchronous rate response; it does not change per-carrier request mapping.
• Other shippingType shapes (third_party, account_number) are outside apiRateRequest and are not validated on the public API unless present as extra root properties.

---

Related: shippingOptions (required block)

Not optional, but often used together with the fields above:

Field	FedEx parcel	UPS parcel
insurance	totalDeclaredValue + per-package declared value	Per-package DeclaredValue (amount split by piece count)
signature	SIGNATURE_OPTION / DIRECT / ADULT / NO_SIGNATURE_REQUIRED	Domestic: package DeliveryConfirmation; international: shipment-level (see internationalOptions)
saturdayDelivery	Applied when rated service includes SATURDAY_DELIVERY surcharge	—
createReturnLabel	Ship/validate only (not rate): return shipment services	—
nonConveyable	Rejected at FedEx/UPS rate prepare	Rejected at UPS/FedEx rate prepare
references, deliveryInstructions, etc.	References on ship; delivery instructions on recipient address	Ship references / delivery instructions

Example request

{
  "shippingOptions": {
    "shippingDate": "2026-05-25"
  },
  "shipper": {
    "personName": "Jane Shipper",
    "addressLine1": "100 Main St",
    "city": "Montreal",
    "provinceCode": "QC",
    "postalCode": "H2X 1Y4",
    "countryCode": "CA",
    "phoneNumber": "5145550100"
  },
  "recipient": {
    "personName": "John Recipient",
    "addressLine1": "200 King St W",
    "city": "Toronto",
    "provinceCode": "ON",
    "postalCode": "M5H 1J1",
    "countryCode": "CA",
    "phoneNumber": "4165550200"
  },
  "packages": {
    "unitOfMeasure": "imperial",
    "pieces": [
      {
        "quantity": 1,
        "weight": 5,
        "length": 10,
        "width": 8,
        "height": 6
      }
    ]
  }
}

Success response (200)

Each item in rates is a sanitized rate record with non-public fields removed (see Rate response shape below). Example:

{
  "data": {
    "requestId": "uuid-rate-request-id",
    "rates": [
      {
        "carrier": {
          "code": "ups-parcel",
          "fullName": { "en": "UPS Parcel" },
          "shortName": { "en": "UPS Parcel" }
        },
        "service": {
          "code": "CA-01",
          "fullName": { "en": "UPS Express", "fr": "UPS Express" },
          "shortName": { "en": "Express", "fr": "Express" },
          "billingCode": "",
          "chips": [],
          "isDisabled": false
        },
        "commitment": {
          "commitDate": "2026-06-03",
          "commitTime": "10:30",
          "timezoneCode": "UTC",
          "guaranteed": true
        },
        "rate": {
          "charges": [
            {
              "code": "BasePrice",
              "type": "base",
              "name": { "en": "Base Rate" },
              "retail": { "amount": 56, "currency": "CAD" },
              "account": { "amount": 55.44, "currency": "CAD" }
            }
          ],
          "totals": {
            "retail": {
              "subtotal": { "amount": 76.3, "currency": "CAD" },
              "tax": { "amount": 2.83, "currency": "CAD" },
              "total": { "amount": 79.13, "currency": "CAD" }
            },
            "account": {
              "subtotal": { "amount": 75.54, "currency": "CAD" },
              "tax": { "amount": 2.8, "currency": "CAD" },
              "total": { "amount": 78.34, "currency": "CAD" }
            }
          },
          "fxRate": 1
        },
        "rateRequestId": "uuid-rate-request-id",
        "rateResponseId": "uuid-use-for-ship",
        "entityType": "rateResponse",
        "createdDate": "2026-06-01T17:07:54.862Z"
      }
    ]
  }
}

Notes:

• rates is built from the rating response. By default (no shippingType in the request) the public API quotes with { "carrier": "all" } and returns every quoted rate, each with its own rateResponseId. Send { "shippingType": { "carrier": "cheapest" } } to get a single cheapest rate only.
• rateResponseId from the chosen rate is required for Ship.

Rate response shape

The public API returns a subset of the full rate response document.

Area	Removed from public API	Kept
Top-level	carrierAccount (includes credentials such as oauthToken), pk, sk, isThirdParty, and other non-public fields	carrier, service, commitment, rate, rateRequestId, rateResponseId, entityType, createdDate
rate.charges[]	margin, discounted, percentage	chips, code, billingCode, name, type, retail, account
rate.totals	discounted tier	retail and account tiers only (subtotal, tax, total each with amount + currency)
rate	—	fxRate

Pricing shown to integrators is retail (list) and account (negotiated) only; margin details are not exposed.

Error responses

HTTP	Condition
400	Validation failed (schema messages joined with ; ), or organization has no userId
401	Missing/invalid/expired API key, wrong integration type
403	Missing shipments:rate scope
422	No rates returned for the shipment (NO_RATES)
500	Internal error