Rate data model

View field support, webhooks, and list parameters for each integration on the Supported Integrations page.

Field	Type	Required	Description
`shipment_id`	string	No	Reference to the shipping object (if rate is for existing shipment)
`currency`	string	No
`from_address`	object	No	Origin address
`from_address.address1`	string	No
`from_address.address2`	string	No
`from_address.city`	string	No
`from_address.region`	string	No
`from_address.region_code`	string	No
`from_address.postal_code`	string	No
`from_address.country`	string	No
`from_address.country_code`	string	No	ISO 2-digit country code
`from_address.name`	string	No	Recipientsender name
`from_address.company_name`	string	No	Company name (for commercial addresses)
`from_address.telephone`	string	No	Phone number (required by FedEx, UPS, DHL)
`from_address.email`	string	No	Email address (for delivery notifications)
`from_address.is_residential`	boolean	No	Alias for address_type === 'RESIDENTIAL'
`from_address.is_validated`	boolean	No	Whether address has been validated
`from_address.delivery_instructions`	string	No	Special delivery notes
`to_address`	object	No	Destination address
`to_address.address1`	string	No
`to_address.address2`	string	No
`to_address.city`	string	No
`to_address.region`	string	No
`to_address.region_code`	string	No
`to_address.postal_code`	string	No
`to_address.country`	string	No
`to_address.country_code`	string	No	ISO 2-digit country code
`to_address.name`	string	No	Recipientsender name
`to_address.company_name`	string	No	Company name (for commercial addresses)
`to_address.telephone`	string	No	Phone number (required by FedEx, UPS, DHL)
`to_address.email`	string	No	Email address (for delivery notifications)
`to_address.is_residential`	boolean	No	Alias for address_type === 'RESIDENTIAL'
`to_address.is_validated`	boolean	No	Whether address has been validated
`to_address.delivery_instructions`	string	No	Special delivery notes
`packages`	ShippingPackage[]	No	Multiple packages (alternative to package)
`packages[].weight`	number	No	Weight of the package
`packages[].weight_unit`	enum	No	Unit for weight (g, kg, oz, lb) Values: `g`, `kg`, `oz`, `lb`
`packages[].length`	number	No	Length of the package
`packages[].width`	number	No	Width of the package
`packages[].height`	number	No	Height of the package
`packages[].size_unit`	enum	No	Unit for dimensions (cm, inch) Values: `cm`, `inch`
`packages[].description`	string	No	Description of the package contents
`packages[].value`	number	No	Declared value of the package
`packages[].currency`	string	No	ISO 4217 currency code
`packages[].tracking_number`	string	No	Package-level tracking (for multi-package shipments)
`packages[].insured_amount`	number	No	Insured value for this package
`ship_by_at`	string (date-time)	No	Latest date to ship (from order) (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
`carrier_id`	string	No	Reference to the carrier
`id`	string	No	Unique identifier for this rate object
`rates`	ShippingRateRate[]	No
`rates[].title`	string	Yes
`rates[].description`	string	No
`rates[].amount`	number	No
`rates[].currency`	string	No
`rates[].base_amount`	number	No	Base shipping rate
`rates[].tax_amount`	number	No
`rates[].discount_amount`	number	No	Applied discount
`rates[].surcharges`	ShippingRateSurcharge[]	No	Additional charges
`rates[].surcharges[].code`	string	No	Surcharge type (e.g., "RESIDENTIAL", "FUEL", "SIGNATURE")
`rates[].surcharges[].name`	string	No	Human-readable name
`rates[].surcharges[].amount`	number	No	Surcharge amount
`rates[].surcharges[].description`	string	No	Description of surcharge
`rates[].rate_source`	string	No	Source of rate (e.g., "carrier", "negotiated", "account")
`rates[].is_negotiated_rate`	boolean	No	Whether this is a negotiated rate
`rates[].estimated_days`	number	No	Estimated delivery time in days
`rates[].delivery_days`	number	No	Delivery days (integer)
`rates[].estimated_delivery_end_at`	string (date-time)	No	Specific delivery date (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
`rates[].estimated_delivery_start_at`	string (date-time)	No	Time window (e.g., "10:00 AM - 2:00 PM") (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
`rates[].delivery_terms`	string	No	Delivery duration terms (e.g., "3-5 business days")
`rates[].transit_hours`	number	No	Transit time in hours
`rates[].is_guaranteed`	boolean	No	Whether delivery is guaranteed
`rates[].package_type`	string	No	Package type (e.g., "package", "envelope", "flat")
`rates[].is_trackable`	boolean	No	Whether shipment is trackable
`rates[].is_active`	boolean	No	Whether rate is currently available

Zod

import { z } from 'zod';

export const ZodShippingRate = z.object({
	shipment_id: z.string().optional().describe("Reference to the shipping object (if rate is for existing shipment)"),
	currency: z.string().optional(),
	from_address: z.object({
			address1: z.string().optional(),
			address2: z.string().optional(),
			city: z.string().optional(),
			region: z.string().optional(),
			region_code: z.string().optional(),
			postal_code: z.string().optional(),
			country: z.string().optional(),
			country_code: z.string().optional().describe("ISO 2-digit country code"),
			name: z.string().optional().describe("Recipientsender name"),
			company_name: z.string().optional().describe("Company name (for commercial addresses)"),
			telephone: z.string().optional().describe("Phone number (required by FedEx, UPS, DHL)"),
			email: z.string().optional().describe("Email address (for delivery notifications)"),
			is_residential: z.boolean().optional().describe("Alias for address_type === 'RESIDENTIAL'"),
			is_validated: z.boolean().optional().describe("Whether address has been validated"),
			delivery_instructions: z.string().optional().describe("Special delivery notes")
}).optional().describe("Origin address"),
	to_address: z.object({
			address1: z.string().optional(),
			address2: z.string().optional(),
			city: z.string().optional(),
			region: z.string().optional(),
			region_code: z.string().optional(),
			postal_code: z.string().optional(),
			country: z.string().optional(),
			country_code: z.string().optional().describe("ISO 2-digit country code"),
			name: z.string().optional().describe("Recipientsender name"),
			company_name: z.string().optional().describe("Company name (for commercial addresses)"),
			telephone: z.string().optional().describe("Phone number (required by FedEx, UPS, DHL)"),
			email: z.string().optional().describe("Email address (for delivery notifications)"),
			is_residential: z.boolean().optional().describe("Alias for address_type === 'RESIDENTIAL'"),
			is_validated: z.boolean().optional().describe("Whether address has been validated"),
			delivery_instructions: z.string().optional().describe("Special delivery notes")
}).optional().describe("Destination address"),
	packages: z.array().optional().describe("Multiple packages (alternative to package)"),
	ship_by_at: z.string-time().optional().describe("Latest date to ship (from order) (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	carrier_id: z.string().optional().describe("Reference to the carrier"),
	id: z.string().optional().describe("Unique identifier for this rate object"),
	rates: z.array().optional(),

});

Python

import dataclasses

@dataclasses.dataclass
class PropertyShippingRateFrom_address:
	address1: Optional[str]
	address2: Optional[str]
	city: Optional[str]
	region: Optional[str]
	region_code: Optional[str]
	postal_code: Optional[str]
	country: Optional[str]
	"""ISO 2-digit country code"""
	country_code: Optional[str]
	"""Recipientsender name"""
	name: Optional[str]
	"""Company name (for commercial addresses)"""
	company_name: Optional[str]
	"""Phone number (required by FedEx, UPS, DHL)"""
	telephone: Optional[str]
	"""Email address (for delivery notifications)"""
	email: Optional[str]
	"""Alias for address_type === 'RESIDENTIAL'"""
	is_residential: Optional[bool]
	"""Whether address has been validated"""
	is_validated: Optional[bool]
	"""Special delivery notes"""
	delivery_instructions: Optional[str]

@dataclasses.dataclass
class PropertyShippingRateTo_address:
	address1: Optional[str]
	address2: Optional[str]
	city: Optional[str]
	region: Optional[str]
	region_code: Optional[str]
	postal_code: Optional[str]
	country: Optional[str]
	"""ISO 2-digit country code"""
	country_code: Optional[str]
	"""Recipientsender name"""
	name: Optional[str]
	"""Company name (for commercial addresses)"""
	company_name: Optional[str]
	"""Phone number (required by FedEx, UPS, DHL)"""
	telephone: Optional[str]
	"""Email address (for delivery notifications)"""
	email: Optional[str]
	"""Alias for address_type === 'RESIDENTIAL'"""
	is_residential: Optional[bool]
	"""Whether address has been validated"""
	is_validated: Optional[bool]
	"""Special delivery notes"""
	delivery_instructions: Optional[str]

@dataclasses.dataclass
class ShippingRate:
	"""Reference to the shipping object (if rate is for existing shipment)"""
	shipment_id: Optional[str]
	currency: Optional[str]
	"""Origin address"""
	from_address: Optional[PropertyShippingRateFrom_address]
	"""Destination address"""
	to_address: Optional[PropertyShippingRateTo_address]
	"""Multiple packages (alternative to package)"""
	packages: Optional[PropertyShippingRatePackages]
	"""Latest date to ship (from order) (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	ship_by_at: Optional[str]
	"""Reference to the carrier"""
	carrier_id: Optional[str]
	"""Unique identifier for this rate object"""
	id: Optional[str]
	rates: Optional[PropertyShippingRateRates]

Are we missing anything? Let us know

Was this page helpful?

Rate data model

TypeScript

Zod

Python