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.
recipient.notes string
Notes from the recipient's contact record, if a contact was used
recipient.groups Array<object>
Groups associated with the recipient's contact record
recipient.federal_tax_id string
Federal tax ID for the recipient, used for international customs declarations. Masked in responses
recipient.state_tax_id string
State tax ID for the recipient. Masked in responses
recipient.tax_identifiers TaxIdentifier[]
Array of tax identifiers for the recipient. Tax ID values are masked in responses

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.
sender.notes string
Notes from the sender's contact record, if a contact was used
sender.groups Array<object>
Groups associated with the sender's contact record
sender.federal_tax_id string
Federal tax ID for the sender, used for international customs declarations. Masked in responses
sender.state_tax_id string
State tax ID for the sender. Masked in responses
sender.tax_identifiers TaxIdentifier[]
Array of tax identifiers for the sender. Tax ID values are masked in responses

destination_contact object
Details about the destination contact for this shipment. This is a separate contact from the recipient, typically representing who will receive the shipment at the destination.

Show Details
destination_contact.name string
Name of the destination contact
destination_contact.email string
Email of the destination contact
destination_contact.phone string
Phone number of the destination contact
destination_contact.business string
Business name of the destination contact
destination_contact.address Address
The parsed address for this destination contact
destination_contact.contact_id string
The ID of the contact record
destination_contact.notes string
Notes from the contact record
destination_contact.groups Array<object>
Groups associated with the contact record

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.

is_parent boolean
Indicates whether this shipment is a parent shipment containing child shipments. A parent shipment represents a consolidated container (e.g., a pallet or box) that holds multiple individual shipments. Defaults to false.

next_children Array<{id: string, tracking_number: string, tracker: {id: string}}>
An array of objects representing the child shipments contained within this parent shipment at the destination. Each entry contains an id, tracking_number, and tracker with the child's tracker ID.

previous_children Array<{id: string, tracking_number: string, tracker: {id: string}}>
An array of objects representing the child shipments contained within this parent shipment at the origin. Each entry contains an id, tracking_number, and tracker with the child's tracker ID.

next_parent_shipment object || null
Reference to the parent shipment at the destination that contains this shipment as a child. Contains an id field. Null if this shipment is not a child of another shipment.

previous_parent_shipment object || null
Reference to the parent shipment at the origin that contains this shipment as a child. Contains an id field. Null if this shipment is not a child of another 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
shipping_label_inference.provider object
The shipping provider detected from the label scan. Contains id (provider identifier, defaults to "other"), name (display name of the provider), logo_url (URL to the provider logo), support_email, support_phone, support_url, service_level, provider_service_level, tracking_number, and tracking_number_barcode
shipping_label_inference.provider.service_level object | null
The service level extracted from the label, with id and name. Null when not detected
shipping_label_inference.provider.provider_service_level object | null
The carrier-specific service level code extracted from the label, with id. Null when not detected
shipping_label_inference.provider.tracking_number string | null
Tracking number extracted from the label
shipping_label_inference.provider.tracking_number_barcode string | null
Raw barcode value for the tracking number extracted from the label
shipping_label_inference.status string
The processing status of the shipping label inference

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
options.generate_label_synchronously boolean
Specifies whether the Shipping Label is to be generated immediately (this is the default behavior: the API takes more time, but label is immediately available) or in the background.

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.

logs Array.<object>
An array of log entries associated with this shipment. Logs capture activity and notes added to the shipment over time.

Show Details
log.id string
Unique identifier for the log entry
log.message string
The content of the log entry
log.visibility string
Controls who can see the log entry
log.images string[]
Array of image URLs attached to the log entry
log.created_at integer
Time in epoch seconds when the log entry was created
log.created_by string
The ID of the user or key who created the log entry

provider object
The shipping provider associated with this shipment. Contains details about the carrier handling the shipment.

Show Details
provider.id string
Unique identifier for the provider (e.g., usps, fedex, dhl). Defaults to other if unknown
provider.name string
Display name of the shipping provider
provider.logo_url string
URL to the provider's logo image
provider.support_email string
Support email address for the provider
provider.support_phone string
Support phone number for the provider
provider.support_url string
URL to the provider's support page

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.incoterm string
The international commercial term governing responsibility, costs, and risk transfer (e.g., DDP, DAP, FCA).
customs.contents_type string
The type of contents being shipped. Possible values: documents, gift, merchandise, returned_goods,
sample, dangerous_goods, humanitarian_donation, other
customs.contents_explanation string
Additional description required when contents_type is other.
customs.eel_type string
ITN/EEL value where applicable.
customs.restriction_type string
Specifies any restrictions that apply to the shipment, such as quarantine or other regulatory requirements.
customs.restriction_comments string
Required when restriction_type is not none.
customs.non_delivery_option string
Indicates the option to be taken if the shipment cannot be delivered (e.g., return, abandon).
customs.items CustomsItem[]
An array of customs items associated with the shipment.

CustomsItem Model

Represents a single line item for customs declaration.

Show Details
item.description string
Description of the item
item.quantity number
Quantity of this item
item.value number
Per-item value in shipment currency (USD by default)
item.weight number
Per-item weight
item.sku string
SKU or product code
item.code string
Product code. If sku is provided, it will be used; otherwise defaults to "N/A"
item.origin_country string
ISO 3166-1 alpha-2 country code where the item originated
item.hs_tariff_number string
Harmonized System code. When destination is not US and an existing code is available, it is preferred
item.currency string
Currency code for value. Defaults to USD
item.mode string
Customs mode. Defaults to "test" for test shipments
item.manufacturer string
Manufacturer name. Defaults to "N/A" if not provided

Tax Identifier Model

Represents a tax identifier for a sender or recipient, used for international shipping and customs.

INFO

Tax ID values are masked in API responses for security. Only the last 4 characters are visible (e.g., "12-3456789" is returned as "******6789").

Show Details
tax_identifier.tax_id string
The tax ID value (max 127 characters). Masked in responses, showing only the last 4 characters
tax_identifier.tax_id_type string
The type of tax ID. Possible values: CNP, DAN, DTF, DUN, EIN, EOR, EORI, FED, FTZ, GST, HMRC, IOSS, OTHER, PAN, PID, SDT, SSN, STA, TAN, TIN, VAT, VOEC, UKIMS
tax_identifier.issuing_country string
ISO 3166-1 alpha-2 country code of the country that issued the tax ID
tax_identifier.entity string
Indicates which party this tax identifier belongs to. Values: SENDER or RECEIVER. This field is set automatically based on whether the identifier was provided on the sender or recipient
Previous <- Shipments Overview
Next Statuses & Events ->