Instant Ship

{primary} Beta Feature: Instant Ship is currently in beta and only available for your own USPS carrier account integrations. Please contact your account manager for more information or contact support.

This method is used to instantly ship a parcel order without first fetching rates. You must specify the service code and shipper ID upfront. This endpoint is optimized for high-volume shipping where you already know which service you want to use.

{info} Results (including label and tracking numbers) are instantly available in the response. They will also be sent to your webhook endpoint if configured.

Endpoint
Request
Request Example
Response
Response Example
Webhook Body
Webhook Body Example

Endpoint

Method	URI	Headers
POST	`/parcel-orders/instant-ship`	default

Request

Field	Required	Type	Description
service	Yes	String	The service code to use for shipping. Please refer to service-names. Currently only USPS services (`USPS-1`, `USPS-2`, `USPS-3`) are supported.
shipper_id	Yes	Integer	The ID of the shipper to use for this shipment. You can find your shipper ID in the shippers page.
from_address_id	No*	Integer	This field is used to identify sender address. You can fetch your saved addresses from address-book. Addresses can be managed from the website on live dashboard or sandbox dashboard. Not required if a "from_address" object was used. Note: If both "from_address_id" and "from_address" fields are defined system will prioritise the "from_address_id"
return_address_id	No	Integer	This field is used to identify return address. You should use the address which is in your saved from addresses. You can fetch your saved from addresses from address-book. Addresses can be managed from the website on live dashboard or sandbox dashboard.
from_address {}	No*	Object	Sender address container. Condition: only required if a "from_address_id" was not used
+name	Yes	String	Name of the sender
+attention	No	String	Attention of the sender
+street_1	Yes	String	Street line 1
+street_2	No	String	Street line 2
+street_3	No	String	Street line 3
+city	Yes	String	City
+zip	Yes	String	Postal Zip code
+state	No*	String	State - This field is required for US or Canada addresses please refer to country-codes
+country	Yes	String	Country (code) for the list please refer to country-codes
+telephone	Yes	String	Telephone Number - This field will will avoid special characters (max 10-15 digits)
+email	No	String	Email
to_address {}	Yes	Object	Receiver address container
+name	Yes	String	Name of the receiver
+attention	No	String	Attention of the receiver
+street_1	Yes	String	Street line 1
+street_2	No	String	Street line 2
+street_3	No	String	Street line 3
+city	Yes	String	City
+zip	Yes	String	Postal Zip code
+state	No*	String	State - This field is required for US or Canada addresses please refer to country-codes
+country	Yes	String	Country (code) for the list please refer to country-codes
+telephone	Yes	String	Telephone Number - This field will will avoid special characters (max 10-15 digits)
+email	No	String	Email
weight_unit	No	String	By default, weight unit is taken from your preferences. However, it can be overwritten using this field. Valid values: `LBS` and `KG`
length_unit	No	String	By default, length unit is taken from your preferences. However, it can be overwritten using this field. Valid values: `IN` and `CM`
package_list []	Yes	Array	An array containing all the package information
+count	Yes	Integer	Pieces count
+box_type	No	String	Carrier box types for the list please refer to Parcel Box Types
+length	Yes	Float	Length
+width	Yes	Float	Width
+height	Yes	Float	Height
+weight	Yes	Float	Weight
+reference_1	No	String	Reference that will appear on the label
+reference_2	No	String	Reference that will appear on the label
+insurance	No	Boolean	Default is `false`. Setting this to `true` would require items information
+is_hazmat	No	Boolean	If the item is hazmat, default is `false`
+signature	No	String	Default is `no_signature`, other options are `adult_signature` and `signature`
+items []	No*	Array	An array containing all items information. Condition: only required on international shipments and shipments with insurance
++quantity	No*	Integer	Quantity of the item Condition: only required when `items []` is used
++price	No*	Float	Price of the item Condition: only required when `items []` is used
++country_of_manufacture	No*	String	Where the item is manufactured needs to be a country code please refer to country-codes. Condition: only required when `items []` is used
++sku	No*	String	SKU. Condition: only required when `items []` is used
++hs_code	No*	String	HS Tariff Code of item. The HS tariff code is an internationally standardized classification system for traded goods, used to determine tariffs and customs duties. Condition: only required when `items []` is used
++description	No*	String	A brief description for customs. Condition: only required when `items []` is used
++content_type	No*	String	Default is Merchandise, acceptable values are Merchandise, Gift, Documents, Sample. Condition: only required when `items []` is used
extra_services []	No	Array	An array containing all the extra services
+saturday_delivery	No	Boolean	Default is `false`.
+certified_mail	No	Boolean	Default is `false`.
+return_receipt	No	Boolean	Default is `false`.
+return_receipt_electronic	No	Boolean	Default is `false`.
+restricted_delivery	No	Boolean	Default is `false`.
customs_details {}	No	Object	Customs details container
+bill_type	No	String	Either `DDU` or `DDP` should be selected, default is `DDP`.
+tax_id_type	No	String	Either `VAT`, `EIN` or `SSN` should be used, default is `null`.
+tax_id	No	String	Default is `null`.
+issuer_country	No	String	Default is `null`.
+aes_itn	No	String	Default is `null`.

Request Example

{
    "service": "USPS-1",
    "shipper_id": 12345678,
    "from_address": {
        "name": "Example Corp",
        "attention": "John Doe",
        "city": "Los Angeles",
        "street_1": "123 S Main St",
        "zip": "90012",
        "state": "CA",
        "country": "US",
        "telephone": "9999999999"
    },
    "to_address": {
        "name": "Example Corp",
        "attention": "John Doe",
        "city": "Flushing",
        "street_1": "123 Main St",
        "zip": "11354",
        "state": "NY",
        "country": "US",
        "telephone": "9999999999"
    },
    "package_list": [
        {
            "length": 5,
            "width": 4,
            "count": 1,
            "weight": 2,
            "height": 1
        }
    ]
}

Response

Field	Type	Description
success	Boolean	true or false
message	String	Message
data	Object	Shipment data container
+shipment_order_id	String	The hash ID of your shipment
+main_tracking_number	String	The main tracking number for the shipment
+label_url	String	Temporary signed URL to download the label (expires in 1 week)

Response Examples

Successful

{
    "success": true,
    "data": {
        "shipment_order_id": "863100211",
        "main_tracking_number": "9400111899223456789012",
        "label_url": "https://labels.deftship.com/863100211.pdf?signature=..."
    },
    "message": "Operation successful!"
}

Failed

{
    "success": false,
    "message": "The given data was invalid.",
    "data": {
        "service": [
            "The service field is required."
        ]
    }
}

Webhook Body

The webhook body is identical to send-parcel.

Webhook Body Example

{
    "shipment_order_id": 123123123,
    "main_tracking_number": "9400111899223456789012",
    "sub_tracking_numbers": ["9400111899223456789012"],
    "package_details": [
        {
            "tracking_number": "9400111899223456789012",
            "items": []
        }
    ],
    "final_price": "8.45",
    "carrier": "usps",
    "service": "USPS Priority Mail",
    "label": "https://labels.deftship.com/863100211.pdf?signature=..."
}

Get Started

Parcel Orders

Batch Shipments

Freight Orders

Pickup Orders

Insurances

Addresses

Others