Deliveries

Models

Delivery Model

The delivery represents a single tracking number with one or more parcels that needs to be delivered. Delivery will always be inbound

object "delivery"
The description of the model.

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

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

coordinates [Number, Number]
The latitude and longitude of the current location.

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

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

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

pickup_at DateTime
The time in epoch seconds when this delivery 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 delivery, prefixed with ship_

status string
Current status for this delivery. See Statuses.

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

paid boolean
Indicates if this delivery was paid for successfully.

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

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

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

invoice_number string
Unique identifier for the delivery's invoice.

reference_number string
User-defined identifier for the delivery.

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

notes string
Additional comments or information about the delivery. 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 delivery.

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 delivery.

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 delivery.

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 delivery's trackers array.

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

tracking_updates TrackingUpdate[]
A list of waypoints this delivery 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 delivery. The URL is in the format https://{domain}/external/shipments/{tracking_number}.

type string
It will always be inbound in case of delivery.

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

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

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

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

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

invoice_id string
Unique identifier for the invoice of this delivery.

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

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

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

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 delivery.

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

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 delivery. This is the first tracker in the delivery's trackers array.

Show Details


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

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

_search object
A special property that will be included if searching through deliveries. 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 delivery.
_search.barcode_values `string[]` Array of barcode values associated with this delivery.
_search.tracking_number `string` Provider-specific string used to track this delivery.
_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 deliveries.

_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 delivery behavior.

Show Details


options.verify_addresses `boolean` Whether to verify addresses for the delivery
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.tracker_chained_status `string` Specifies the status when multiple deliveries are linked in sequence. Default value is package_at_waypoint
options.tracker_auto_close_shipments_option `string` Controls when previous deliveries 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 deliveries in a chain. When auto_close_shipments_option is enabled, previous deliveries will be marked with this status. It's default value will be delivered

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

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

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

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

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

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

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 delivery, such as quarantine or other regulatory requirements.
customs.non_delivery_option `string` Indicates the option to be taken if the delivery cannot be delivered.
customs.items `string[]` An array of customs items associated with the delivery.

Models

# Delivery Model

Delivery Model