1. Shipments
  2. Models

Shipments

Models

Shipment Model

Whether you are fetching shipping rates, purchasing a label, or tracking a shipment, we will always have the same model for you. We standardize the data from every carrier to make responses as predictable as possible.

object "shipment"
The description of the model.

amount integer
The amount collected for this shipment from the customer as an Integer. $13.78 is saved as 1378.

billed_amount integer
The amount billed to you for this shipment.

coordinates Array<Number, Number>
The latitude and longitude of the current location

created_at integer
Time in epoch seconds when this shipment was created.

currency string
The lowercase three-character code for the currency used for this transaction.

estimated_delivery_at integer
The estimated delivery for this shipment in epoch seconds.

fulfillment_id string
The ID of the fulfillment that created this shipment.

id string
Unique identifier for the shipment.

invoice_id string
Unique identifier for the invoice of this shipment.

kiosk_id string
This kiosk that was used to generate this shipment.

label_url string
URL for the shipping label in the size and format specified in the dashboard.

lead_time_mins integer
The amount of lead time needed to prepare the shipment for an on-demand courier. This is set up in the dashboard.

metadata object
Key value pairs of data that you can set for this shipment.

options object
Options that were passed in when generated shipping rates.

Show Details
options.provider_timeout integer
The amount of time in milliseconds to wait for a shipping provider before discarding it's results.
options.verify_address boolean
If all addresses for the shipment should be verified
options.checkout_total integer
The total price in USD cents for the cart total during an e-commerce purchase.
options.request_provider_pickup boolean
If the shipping provider should pick up this package.
options.providers Array<string>
The list of shipping provider IDs that you want returned.
options.service_levels Array<string>
The list of service level IDs that you want returned.
options.max_delivery_days integer
The maximum number of delivery days for this shipment.
options.rate_types "in_person_pickup","curbside_pickup","locker_pickup","provider_delivery","offline_delivery"
The type of rate that should be returned for the shipment.

customs_info object
Custom information that was passed in to fetch customs rate. Currently this supports Puerto Rico and Virgin Islands only

Show Details
customs_info.customs_signer string
Signer of the shipment
customs_info.contents_type string
Type of the content, Possible values: documents, gift, merchandise ,returned_goods ,sample ,dangerous_goods ,humanitarian_donation ,other
customs_info.restriction_type string
Any type of restriction applied, Possible values: none, other, quarantine, sanitary_phytosanitary_inspection
customs_info.restriction_comments boolean
Required if restriction_type is not "none"
customs_info.customs_items Array<customs_items>
The list of items have customs information for each item

customs_items object[]
The details of each items in the shipment on which customs is applied.

Show Details
customs_items.description string
Description of the custom item
customs_items.hs_tariff_number string
Harmonized Tariff Number which can be search on https://hts.usitc.gov/. Example: 6109.10.00. Breakdown of example: Chapter: 61, Subchapter: 09, Tariff number from table: 10.00
customs_items.origin_country string
Any type of restriction applied, Possible values: none, other, quarantine, sanitary_phytosanitary_inspection
customs_items.quantity boolean
Quantity of item
customs_items.value boolean
Value of item
customs_items.code boolean
Product identifier
customs_items.manufacturer boolean
Manufacturer of item "none"
customs_items.currency boolean
Three-character currency code. Defaults to "USD"
customs_items.weight Array<customs_items>
Total weight (unit weight * quantity). Must be greater than zero.

organization_id string
Unique identifier for the organization that owns this shipment. This will always be your organization ID.

paid boolean
If this shipment was paid for successfully.

parcels Array.<Parcel>
All parcels in the fulfillment and the inventory packed within them

Show Details
Parcel.object "parcel"
The enum for this object
Parcel.attributes Array.<"alcohol", "marijuana", "pharma", "dry_ice", "lithium">
Indicates certain aspects of the item that will impact shipping and handling
Parcel.id string
The unique ID assigned to the parcel beginning with prcl_
Parcel.length float
The length of the parcel in inches
Parcel.width float
The width of the parcel in inches
Parcel.height float
The height of the parcel in inches
Parcel.weight float
The weight of the parcel in pounds (lbs)
Parcel.type enum
The type of package if selecting from carrier specific packaging. See Predefined Packages
Parcel.special_handling string
Special handing instructions for the parcel.
Parcel.tracking_number string
The tracking number for this parcel if a shipment was purchased
Parcel.label_url string
The shipping label PDF for this parcel if a shipment was purchased
Parcel.inventory Inventory
The inventory packed inside of the parcel

payment_reference string
A reference for the payment of this shipment. This will be visible on the invoice.

pickup_at integer
The time in epoch seconds when this shipment will be picked up.

provider object
Details about the shipping carrier.

Show Details
provider.id string
Unique ID for the provider.
provider.logo_url string
Logo of the provider.
provider.marketplace boolean
If this shipping provider came from the PackageX marketplace.
provider.name string
Name of the provider.
provider.support_email string
Email to contact support for this provider, available for on demand couriers.
provider.support_phone string
Phone to contact support for this provider, available for on demand couriers.
provider.support_url string
URL to contact support for this provider, available for on demand couriers.
provider.support_reference string
A support reference code that some providers use to help customers.

purchased_rate Rate
Rate class being used for this shipment. See Rate.

rates array<Rate>
All rates returned for this shipment. See Rate.

recipient object
Details about the contact receiving this shipment.

Show Details
recipient.address Address
The parsed address for this recipient
recipient.email string
Email for the recipient. Recipient will receive tracking notifications here
recipient.phone string
Phone number of the recipient. On demand couriers may contact this number for issues
recipient.name string
Name of the recipient, printed on the shipping label
recipient.contact_id string
The ID of the contact if one was used to create this recipient.

refund_status null|"requested"|"refunded"|"rejected"
The status of the refund on this shipment if one was requested. Funds will be returned back when the status is refunded, which varies with time based on the shipping provider.

sender object
Details about the contact sending this shipment.

Show Details
sender.address Address
Parsed address for the sender.
sender.email string
Email for the sender.
sender.phone string
Phone number of the sender. On demand couriers may contact this number for issues.
sender.name string
Name of the sender, printed on the shipping label
sender.contact_id string
The ID of the contact if one was used to create this sender.

status string
Current status for this shipment. See Statuses.

tracking_number string
Provider-specific string used to track this shipment. See Rate.

tracking_updates Array.<TrackingUpdate>
An array of waypoints this shipment had in order from oldest to newest.

Show Details
TrackingUpdate.address Address
The address of the package at this waypoint. Address details are often limited to use the city and state when in transit.
TrackingUpdate.comment string
A comment left by the provider about this update
TrackingUpdate.created_at integer
Time in epoch seconds when this update occurred
TrackingUpdate.event string
The latest event that occurred at this waypoint. See Shipment Events
TrackingUpdate.hash string
A unique hash for this update to make it easier to identify duplicates in webhooks.
TrackingUpdate.images Array<string>
An array of URLs to images about this update. Commonly used by on demand couriers for picture proof of delivery
TrackingUpdate.layout_id string
The ID of the layout that this item is on, if it matches one of your locations.
TrackingUpdate.layout object
The layout object of the location of this update, if it is one of your locations.
TrackingUpdate.location_id string
The ID of the location of this update, if it is one of your locations.
TrackingUpdate.message string
User-friendly message generated by PackageX to let a customer know about their shipment status
TrackingUpdate.status string
The status code for this update See Statuses
TrackingUpdate.updated_at integer
The time in epoch seconds when this status was last updated

tracking_url string
URL where a user can go to track their packages.

type "outbound" | "inbound"
Indicates whether the shipment is an inbound or outbound shipment.

updated_at integer
Time in epoch seconds when this shipment was last updated.

_search object
A special property that will be included if searching through shipments. This is a flat object which will include <mark> tags around characters that have matched the search. You can use this to more easily highlight text for a user interface.

Show Details
_search.id string
The ID of the shipment.
_search.tracking_number string
The tracking number.
_search.sender_name string
The sender's name. It will also match common nicknames.
_search.sender_email string
The sender's email.
_search.sender_phone string
The sender's phone.
_search.sender_formatted_address string
The sender's full address string.
_search.recipient_name string
The recipient's name. It will also match common nicknames.
_search.recipient_email string
The recipient's email.
_search.recipient_phone string
The recipient's phone.
_search.recipient_formatted_address string
The recipient's full address string.
_search.provider_name string
The shipping provider's name.
_search.provider_id string
The shipping provider's ID
_search.relevance_score ?number
A number from 0 - 1 about how relevant the result was to the search query, with 1 being a perfect match.


Rate Model

This is how all rates are returned on the platform. Initially when you are creating rates, you'll typically have many options here. When it's time to purchase the rate, you'll pass the id of the rate you want to buy.

object "rate"
The description of the model.

amount integer
The amount that will be displayed for this rate.

billed_amount integer
The amount you will be charged for this rate if purchased. Can be higher or lower than amount if you are discounting or upcharging your shipment.

carrier_account string
The carrier account used for this rate, if provided.

created_at Integer
Seconds from epoch when this rate was created.

id String
Unique identifier for this rate. This ID is passed to purchase a rate.

pickup_at Integer
The time in epoch seconds when this shipment will be picked up for this rate. If this shipment does not include a pickup, it will be null.

provider object
The details of the carrier or courier for this shipment.

Show Details
provider.id string
Unique ID for the provider
provider.logo_url string
Logo of the provider
provider.marketplace boolean
If this provider came from the PackageX marketplace
provider.name string
Name of the provider
provider.support_email string
Email to contact support for this provider, available for on demand couriers
provider.support_phone string
Phone to contact support for this provider, available for on demand couriers
provider.support_url string
URL to contact support for this provider, available for on demand couriers

service_level object
The data about the service level for this delivery.

Show Details
service_level.days integer
The expected days that this delivery will take
service_level.estimated_delivery_at integer
Time in epoch seconds when the delivery is estimated to take place
service_level.id String
The ID of the service level
service_level.name String
The name of the service label for customers to understand, e.g: Same Day or Next Day Air
service_level.pickup_at Integer
The time in epoch seconds when this shipment will be picked up for this rate
service_level.terms string
The user-friendly string about the service, such as "1 day delivery" or "Today by 9pm"


Previous <- Shipments Overview
Next Statuses & Events ->