1. Shipments
  2. Models

Shipments

Models

Shipment Model

Whether you are fetching shipping rates, purchasing a label, or tracking a shipment, we provide a standardized model across all carriers to ensure consistent and predictable responses.

object "shipment"
The description of the model.

amount integer
The amount collected for this shipment from the customer.

billed_amount integer
The amount billed to you for this shipment. If not specified, defaults to the amount field.

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

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

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

rates_generated_at DateTime
Time in epoch seconds when rates were last generated for this shipment.

estimated_delivery_at DateTime
The estimated delivery time for this shipment in epoch seconds.

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

currency string
The lowercase three-character code for the currency used for this transaction. Defaults to "usd".

id string
Unique identifier for the shipment, prefixed with ship_

status string
Current status for this shipment. Follows the standardized status configuration. See Statuses.

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

paid boolean
Indicates if this shipment was paid for successfully.

parcels Parcel[]
A list of parcels associated with this shipment. Empty array if no parcels are present.

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

purchased_rate Rate
The selected rate used for this shipment. See Rate model for details.

recommended_rate Rate
The recommended rate is the lowest billed_amount rate. See Rate model for details.

rates Rate[]
All rates returned for this shipment. See Rate model for details.

rma_number string
Unique identifier for return shipments, used for processing returns.

invoice_number string
Unique identifier for the shipment's invoice.

reference_number string
User-defined identifier for the shipment.

purchase_order string
Purchase order number for the shipment, either user-defined or scanned from the shipping label.

account_id string
Carrier-specific account identifier used for billing and rate calculations. Can be either manually specified or automatically extracted from scanned shipping labels.

notes string
Additional comments or information about the shipment. Limited to 255 characters.

provider_id string
Unique identifier for the shipping provider (e.g., usps, fedex, dhl). Can also be self for your own private rates. See Providers for details.

recipient object
Details about the contact receiving this shipment.

Show Details
recipient.name string
Name of the recipient, printed on the shipping label
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.business string
Business name of the recipient, if applicable
recipient.address Address
The parsed address for this recipient
recipient.contact_id string
The ID of the contact if one was used to create this recipient.

designated_recipient object
Details about the alternate contact designated to receive this shipment.

Show Details
designated_recipient.name string
Name of the designated recipient
designated_recipient.email string
Email for the designated recipient
designated_recipient.phone string
Phone number of the designated recipient
recipient.business string
Business name of the designated recipient, if applicable
designated_recipient.address Address
The parsed address for this designated recipient
designated_recipient.contact_id string
The ID of the contact if one was used to create this designated recipient

sender object
Details about the contact sending this shipment.

Show Details
sender.name string
Name of the sender, printed on the shipping label
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.business string
Business name of the sender, if applicable
sender.address Address
The parsed address for this sender.
sender.contact_id string
The ID of the contact if one was used to create this sender.

tracker_id string
This is the ID of the first tracker in the shipment's trackers array.

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

tracking_updates TrackingUpdate[]
A list of waypoints this shipment has passed through, ordered from oldest to newest. See Tracking Update Model for object attributes.

tracking_url string
A publicly accessible URL where anyone can view the tracking information for this shipment. The URL is in the format https://{domain}/external/shipments/{tracking_number}.

type string
Indicates whether the shipment is an inbound or outbound shipment. Defaults to outbound

organization_id string
Unique identifier for the organization that owns this shipment.

fulfillment_id string
The ID of the fulfillment associated with this shipment.

manifest_id string
The ID of the manifest associated with this shipment.

order_number string
Order number associated with this shipment. If the shipment was created from a fulfillment, this will be the fulfillment's order number.

container_id string
The ID of the container that this shipment is grouped into.

invoice_id string
Unique identifier for the invoice of this shipment.

location object
Details about the location where this shipment is currently located. See Location Model for more details.

location_id string
ID of the location where this shipment is currently located. This can be either directly set on the shipment or derived from the latest tracking update.

layout_id string
ID of the layout where this shipment is currently located. This can be either derived from the latest tracking update or directly set on the shipment.

layout object
The layout object of the location of this update. See Layout Model for more details.

inference_id string
ID of the shipping label scan that created this shipment.

shipping_label_inference object
Details about the shipping label scan that created this shipment.

Show Details
shipping_label_inference.id string
Unique identifier for the shipping label scan
shipping_label_inference.image_url string
URL of the scanned shipping label image
shipping_label_inference.media_urls string[]
Array of URLs for any additional media associated with the scan

tracker object
Details about the primary tracker for this shipment. This is the first tracker in the shipment's trackers array.

Show Details
tracker.id string
Unique identifier for the tracker
tracker.destination_layout object
The layout where this shipment is expected to arrive
tracker.destination_location object
The location where this shipment is expected to arrive
tracker.destination_contact object
The contact who is expected to receive this shipment

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

refund_status string
The refund status indicates the current stage of a refund request for a shipment. It can be null as well if no refund request has been requested. See Statuses

_search object
A special property that will be included if searching through shipments. This is a flat object that contains various properties related to the search results. Each property may include <mark> tags around characters that have matched the search query, allowing for easy highlighting in the user interface. The properties within this object provide relevant information about the search results, such as order number, barcode values, tracking number, sender name, sender email, recipient name, recipient email, provider name, relevance score and the original query used for the search.

Show Details
_search.order_number string
Order number associated with this shipment.
_search.barcode_values string[]
Array of barcode values associated with this shipment.
_search.tracking_number string
Provider-specific string used to track this shipment.
_search.sender_name string
Name of the sender.
_search.sender_email string
Email for the sender.
_search.recipient_name string
Name of the recipient.
_search.recipient_email string
Email for the recipient.
_search.provider_name string
The shipping provider's name.
_search.relevance_score number
A numeric value between 0 and 1 that indicates the relevance of a search result to the query, where 1 represents a perfect match and higher values indicate better matches.
_search.query string
The original search query used to find matching shipments.

_searchV2 object
A special property that will be included if searching through shipments. This is the result of the new advanced search.

Show Details
_search.scores Scores
An object representing the various scores calculated
_search.shipment object
This is a subset of the shipment model that will only include those properties where there is some matched content 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.

options object
Options that control rate generation and shipment behavior.

Show Details
options.provider_timeout integer
Time in milliseconds to wait for provider responses when generating rates
options.verify_addresses boolean
Whether to verify addresses for the shipment
options.checkout_total integer
Total amount in USD cents for e-commerce checkout
options.lead_time_mins integer
Lead time in minutes needed for pickup preparation
options.provider_instructions string
Special instructions for the shipping provider
options.same_day_tip_amount integer
Tip amount in cents for same-day delivery
options.request_provider_pickup boolean
Whether to request provider pickup service
options.providers string[]
Array of provider IDs
options.service_levels string[]
Array of service level IDs
options.max_delivery_days integer
Maximum acceptable delivery days
options.rate_types string[]
Array of shipment rate types. Can be one of delivery, pickup, or received
options.return_other_rates boolean
Whether to return rates beyond the filtered ones
options.tracker_chained_status string
Specifies the status when multiple shipments are linked in sequence. Default value is
package_at_waypoint
options.tracker_auto_close_shipments_option string
Controls when previous shipments in a chain should be automatically closed. It's default value will be
on_provider_updates
options.tracker_auto_close_shipments_status string
Specifies which status to apply when automatically closing previous shipments in a chain. When
auto_close_shipments_option is enabled, previous shipments will be marked with this status.
It's default value will be delivered

checksum string
A hash value computed from the current shipment configuration. This value gets updated whenever the shipment updates.

updated_by string
The ID of the user or key who last updated the shipment.

user_id string
Unique identifier for the user associated with this shipment. This field is derived from the user's profile and can be null if no user is associated with the shipment.

barcode_values string[]
Array of barcode values associated with this shipment. These values can be scanned from shipping labels or manually added.

tags string[]
An array of tags associated with this shipment. These tags are derived from the predefined shipment tags defined in the SHIPMENT_TAGS enum.

customs object
An object containing customs information for the shipment. This field will be null if there are no custom items associated with this shipment.

Show Details
customs.signer string
The name of the individual who is responsible for signing the customs declaration.
customs.certify boolean
Indicates whether the signer certifies that the information provided is accurate and complete.
customs.contents_type string
The type of contents being shipped. Possible values: documents, gift, merchandise, returned_goods,
sample, dangerous_goods, humanitarian_donation, other
customs.restriction_type string
Specifies any restrictions that apply to the shipment, such as quarantine or other regulatory requirements.
customs.non_delivery_option string
Indicates the option to be taken if the shipment cannot be delivered.
customs.items string[]
An array of customs items associated with the shipment.

Previous <- Shipments Overview
Next Statuses & Events ->