Reference: Shipment API

A shipment represents the delivery of items to the end customer.

The Shipment object

A Shipment is associated with:

  • A single Purchase Order
  • A single Shipper (carrier)
  • One or more Order Items
  • One or more Shipment Trackings (packages with distinct tracking numbers)

Each Shipment has the following attributes:

Field Description
id The unique numeric identifier for the shipment. This is assigned by Duoplane and cannot be changed. (Readonly)
purchase_order_id The unique numeric identifier for the purchase order. This is assigned by Duoplane and cannot be changed. (Readonly)
created_at The date and time in UTC when the shipment was created. (Readonly)
updated_at The date and time in UTC when the shipment was last updated. (Readonly)
purchase_order_public_reference

The purchase order number assigned to the purchase order.

This value is unique for a given retailer. (Readonly)

shipper_id The unique numeric identifier for the shipment's carrier.
shipper_name The name of the shipment's carrier. If creating a shipment, this value must match an existing carrier in the retailer's Duoplane account.
shipper_scac_code The SCAC code of the shipment's carrier, if available.
vendor_invoice_reference Vendor invoice number associated with this shipment
vendor_shipping_cost

Shipping fee charged by vendor

May be omitted from the response shipping fees are not enabled.

vendor_handling_cost

Handling fee charged by vendor

May be omitted from the response handling fees are not enabled.

vendor_tax_cost

Taxes charged by vendor

May be omitted from the response if taxes are not enabled.

shipper_invoice_reference Carrier invoice number associated with this shipment
shipper_shipping_cost Shipping fee charged by carrier
shipment_trackings_attributes

An array of tracking number attributes. Each tracking number has the following attributes:

  • id: The unique numerical ID assigned to this tracking number by Duoplane.
  • tracking: The tracking number as provided by the carrier.
shipment_items_attributes

An array of items on the shipment. Each item has the following attributes:

  • id: The unique numerical ID assigned to this shipment item by Duoplane.
  • order_item_id: The unique numerical ID of the associated Order Item, as assigned by Duoplane.
  • quantity: The quantity shipped of this item on this shipment.
  • cost: The wholesale cost of this item. The cost is the same as what appears for this item on the associated purchase order.
  • order_item_name: The name of the line item.
  • serial_codes: An array of serial numbers / codes associated with this shipment item.

Retrieve a list of shipments

GET https://app.duoplane.com/shipments.json

All request parameters must be nested in a hash / associative array with the key "search". E.g.:

?search[retailer_id]=1
Search Parameter Description
purchase_order_number The purchase order number as it appears on the purchase order.
customer_name

The name of the customer on the shipping address of this purchase order.

Partial matches are allowed. (E.g. a search for "B Smi" will find "Bill Smith".)

vendor_invoice_reference The vendor invoice number.
tracking

The tracking number of the shipment.

Partial matches are allowed. (E.g. a search for "1Z" will find "1Z1234".)

vendor_id The Duoplane-assigned unique numeric ID of the vendor on the shipment's purchase order.
retailer_id The Duoplane-assigned unique numeric ID of the retailer on the shipment's purchase order.
created_at_min Retrieve only shipments created after this time.*
created_at_max Retrieve only shipments created before this time.*
updated_at_min Retrieve only shipments updated after this time.*
updated_at_max Retrieve only shipments updated before this time.*
invoiced_at_min Retrieve only shipments whose invoice numbers were entered after this time.*
invoiced_at_max Retrieve only shipments whose invoice numbers before this time.*

 

* Times should be in ISO 8601 format with time zone or zone offset. If not explicitly provided, the time zone is assumed to be that of the requesting API user.

Pagination

In addition to the search filters, you can specify paging parameters:

Paging Parameter Description
per_page

 

The maximum number of records to return with each call. The default and maximum value is 250.

page

 

If the count of records matching the search exceeds the number that are returned in a single response, the page number for subsequent requests.

Option flag

In addition to the search filters, you can specify this option flag:

Option Flag Description
include_shipment_purchase_order Set to "1" to "true" in order to have the returned shipment objects include the associated purchase order object.

Create a new shipment

POST https://app.duoplane.com/purchase_orders/#{purchase_order_id}/shipments.json

To mark Order Items as fulfilled, create a Shipment and associate Order Items to that Shipment as Shipment Items.

Each Shipment must contain at least one Shipment Item and at least one tracking number (Shipment Tracking).

Sample request:

Note that only one of the following should be included to specify the carrier: shipper_id, shipper_name, or shipper_scac_code

POST https://app.duoplane.com/purchase_orders/987654/shipments.json
{
    "shipment": {
    	"shipper_name": "UPS",
	"vendor_shipping_cost": "",
	"vendor_handling_cost": "",
	"vendor_invoice_reference": "AB1234",
	"shipper_shipping_cost": 5.0,
    	"shipment_items_attributes": [
    		{
    			"order_item_id": 239417,
    			"quantity": 1
    		},
    		{
    			"order_item_id": 239418,
    			"quantity": 2
    		}
    	],
    	"shipment_trackings_attributes": [
    		{
    			"tracking": "1234"
    		},
    		{
    			"tracking": "5678"
    		}
    	]
        
    }
}
 

Update an existing shipment

PUT https://app.duoplane.com/shipments/#{shipment_id}.json

Sample request: Note that some shipment attributes fields might be readonly if the shipment data has already synced to either the ecommerce platform or to an external accounting system.

PUT https://app.duoplane.com/shipments/987654.json
{
    "shipment": {
	"vendor_shipping_cost": "3.5",
	"vendor_invoice_reference": "AB1234",
    }
}
 

Carrier options

Common options for the Shipper (carrier) are:

shipper_id shipper_name shipper_scac_code
1 UPS UPSN
2 FedEx FEDX
17 US Postal USPS
395

DHL eCommerce

 

 

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.