Create a rate

POST/shipping/{connection_id}/rate

Parameters

fieldsstring array
Fields to return
rawstring
Raw parameters to include in the 3rd-party request. Encoded as a URL component. eg. raw parameters: foo=bar&zoo=bar -> raw=foo%3Dbar%26zoo%3Dbar
connection_idstring required
ID of the connection

Payload

shipment_idstring
Reference to the shipping object (if rate is for existing shipment)
currencystring
from_addressobject
Origin address
to_addressobject
Destination address
packages array
Multiple packages (alternative to package)
ship_by_atdate-time
Latest date to ship (from order) (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
carrier_idstring
Reference to the carrier
idstring
Unique identifier for this rate object
rates array

Returns

Response fieldTypeRequiredDescription
shipment_idstringNoReference to the shipping object (if rate is for existing shipment)
currencystringNo
from_addressobjectNoOrigin address
from_address.address1stringNo
from_address.address2stringNo
from_address.citystringNo
from_address.regionstringNo
from_address.region_codestringNo
from_address.postal_codestringNo
from_address.countrystringNo
from_address.country_codestringNoISO 2-digit country code
from_address.namestringNoRecipientsender name
from_address.company_namestringNoCompany name (for commercial addresses)
from_address.telephonestringNoPhone number (required by FedEx, UPS, DHL)
from_address.emailstringNoEmail address (for delivery notifications)
from_address.is_residentialbooleanNoAlias for address_type === 'RESIDENTIAL'
from_address.is_validatedbooleanNoWhether address has been validated
from_address.delivery_instructionsstringNoSpecial delivery notes
to_addressobjectNoDestination address
to_address.address1stringNo
to_address.address2stringNo
to_address.citystringNo
to_address.regionstringNo
to_address.region_codestringNo
to_address.postal_codestringNo
to_address.countrystringNo
to_address.country_codestringNoISO 2-digit country code
to_address.namestringNoRecipientsender name
to_address.company_namestringNoCompany name (for commercial addresses)
to_address.telephonestringNoPhone number (required by FedEx, UPS, DHL)
to_address.emailstringNoEmail address (for delivery notifications)
to_address.is_residentialbooleanNoAlias for address_type === 'RESIDENTIAL'
to_address.is_validatedbooleanNoWhether address has been validated
to_address.delivery_instructionsstringNoSpecial delivery notes
packagesShippingPackage[]NoMultiple packages (alternative to package)
packages[].weightnumberNoWeight of the package
packages[].weight_unitenumNoUnit for weight (g, kg, oz, lb) Values: g, kg, oz, lb
packages[].lengthnumberNoLength of the package
packages[].widthnumberNoWidth of the package
packages[].heightnumberNoHeight of the package
packages[].size_unitenumNoUnit for dimensions (cm, inch) Values: cm, inch
packages[].descriptionstringNoDescription of the package contents
packages[].valuenumberNoDeclared value of the package
packages[].currencystringNoISO 4217 currency code
packages[].tracking_numberstringNoPackage-level tracking (for multi-package shipments)
packages[].insured_amountnumberNoInsured value for this package
ship_by_atstring (date-time)NoLatest date to ship (from order) (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
carrier_idstringNoReference to the carrier
idstringNoUnique identifier for this rate object
ratesShippingRateRate[]No
rates[].titlestringYes
rates[].descriptionstringNo
rates[].amountnumberNo
rates[].currencystringNo
rates[].base_amountnumberNoBase shipping rate
rates[].tax_amountnumberNo
rates[].discount_amountnumberNoApplied discount
rates[].surchargesShippingRateSurcharge[]NoAdditional charges
rates[].surcharges[].codestringNoSurcharge type (e.g., "RESIDENTIAL", "FUEL", "SIGNATURE")
rates[].surcharges[].namestringNoHuman-readable name
rates[].surcharges[].amountnumberNoSurcharge amount
rates[].surcharges[].descriptionstringNoDescription of surcharge
rates[].rate_sourcestringNoSource of rate (e.g., "carrier", "negotiated", "account")
rates[].is_negotiated_ratebooleanNoWhether this is a negotiated rate
rates[].estimated_daysnumberNoEstimated delivery time in days
rates[].delivery_daysnumberNoDelivery days (integer)
rates[].estimated_delivery_end_atstring (date-time)NoSpecific delivery date (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
rates[].estimated_delivery_start_atstring (date-time)NoTime window (e.g., "10:00 AM - 2:00 PM") (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
rates[].delivery_termsstringNoDelivery duration terms (e.g., "3-5 business days")
rates[].transit_hoursnumberNoTransit time in hours
rates[].is_guaranteedbooleanNoWhether delivery is guaranteed
rates[].package_typestringNoPackage type (e.g., "package", "envelope", "flat")
rates[].is_trackablebooleanNoWhether shipment is trackable
rates[].is_activebooleanNoWhether rate is currently available

Errors

Errors return the HTTP status code and a JSON body with statusCode, error (the short label) and message (a human-readable detail).

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests to unified.to API; max requests per minute: N"
}
StatusErrorMeaning
400Bad RequestThe request was malformed or failed validation.
401UnauthorizedThe connection is likely broken; re-authorize it.
403ForbiddenThe connection is missing permissions or scopes.
404Not FoundThe requested resource does not exist.
429Too Many RequestsRate limit exceeded (see the two sources below).
500Internal Server ErrorAn unexpected error occurred.
501Not ImplementedNot supported by this integration.

Errors from the underlying integration pass through: the integration's status comes back as ours (429, 401, 403, 404 or 5xx), usually with its message. When the integration's error body is unclear, Unified extracts what it can and returns a clearer message.

429 Too Many Requests

A 429 has two possible sources:

  • The integration's own rate limit, passed through.
  • Unified's workspace limit: a rolling 60 seconds, set by plan, with the message Too many requests to unified.to API; max requests per minute: N.
const options = {
  method: 'POST',
  url: 'https://api.unified.to/shipping/5de520f96e439b002043d8dc/rate',
  headers: {
    authorization: 'bearer .....'
  },
  data: undefined,
  params: {
    fields: '',
    raw: '',
  }
};

const results = await axios.request(options);
Are we missing anything? Let us know
Was this page helpful?