Table of Contents
Other Shipping Options
There are many advanced cases for shipping options that ShipStream supports. Some of these may be graduated to separate fields in the future but the Other Shipping Options field for Orders offers a way to support these fields now.
The field called "Other Shipping Options" may be used when the order is created and also afterward by clicking "Edit" on the Shipping & Handling Information section. This field is also available to use in Imports, API integrations and Scripts.
The Other Shipping Options field must be specified as valid JSON-encoded object or in the context of a script as an "object" (which will automatically be converted into JSON).
For example, to set these fields in a Before Create Order script:
order.options.other_shipping_options = {...}While this JSON object may contain any data, the specific fields which may affect ShipStream's operation are described below.
Multiple Fields
Multiple options may be combined by merging them into one object. For example to specify both "packaging" and "amazon_order_id" the JSON object may be specified like so:
{
"amazon_order_id":"903-9939455-1336669",
"packaging":[{"sku":"amazon_flier"}]
}External Shipping Methods
All "Other Shipping Options" data will also be passed through to the External Shipping Methods API Endpoint URL verbatim and it is up to the custom endpoint to implement these features for them to be supported.
Packaging Features
You may attach Packaging Features to an order using the packaging key. See Attaching Packaging Features to Orders for more detailed information.
packaging
The value must be an array of objects and each element should conform to the following format:
- Either the
skuorproduct_idof the Packaging Feature - And if the Packaging Feature should apply to specific order items, and array of the SKUs of the items to which it should apply.
Example
{
"packaging": [
{ "product_id": 62},
{ "sku": "TapeLid"},
{ "sku": "BubbleWrap", "items": ["34-737-8757", "29-329-5002"]}
]
}Virtual Shipping Methods
Finer control can be exerted over the selection of the appropriate shipping service for orders with Virtual Shipping Methods by using the following keys:
virtual_excluded_services
When an order is assigned to a virtual shipping method, you can restrict which real shipping methods may NOT be resolved for the order using this key.
The value must be an array and each element of the array must be a string which is either an exact match for a real shipping service code, or if the string begins with "/" the value must be a valid regular expression matching a real shipping service code. All services that match the regular expressions or exact strings will be excluded from the service selection process. If no eligible services are allowed an error will be thrown.
Example
{
"virtual_excluded_services":[
"fedex_SMART_POST",
"/^usps_/"
]
}Amazon Merchant Fulfillment
Advanced options for Amazon Merchant Fulfillment may be specified using the following keys:
amazon_site
The "Site ID" of the Amazon Marketplace which the order belongs to. This is a country code and if not specified will default to the US marketplace. This field should not be specified if amazon_marketplace_id is also specified.
Example
{"amazon_site":"MX"}amazon_marketplace_id
The "Marketplace ID" of the Amazon Marketplace which the order belongs to. This is a 13-14 character string which starts with "A". For example, the Marketplace ID for the Mexican Amazon Marketplace is "A1AM78C64UM0Y8". This field should not be specified if amazon_site is also specified.
Example
{"amazon_marketplace_id":"A1AM78C64UM0Y8"}amazon_order_id
By default ShipStream will look for an Amazon order ID in the Order # or Order Ref # fields. If for some reason you cannot place the Amazon order ID in one of these fields you can use this key in the Other Shipping Options to set the Amazon order ID.
Example
{"amazon_order_id":"903-9939455-1336669"}amazon_excluded_services
Amazon Merchant Fulfillment works by returning multiple "eligible" services on a per-order basis. You can restrict which ones ShipStream may choose through the configuration (see Amazon Merchant Fulfillment). Additionally, you can exclude specific services on a per-order basis using this key.
The value must be an array and each element of the array must be a string which is either an exact match for a "ShippingServiceId" (see the full list), or if the string begins with "/" the value must be a valid regular expression matching a "ShippingServiceId". All services that match the regular expressions or exact strings will be excluded from the service selection process. If no eligible services are allowed an error will be thrown.
Example
{
"amazon_excluded_services":[
"DHLMX_PTP_PACKAGE_EXPRESS",
"/^USPS_/"
]
}Reference Numbers
See Reference Numbers for more detailed information on using custom reference numbers.
reference_numbers
The value must be an object with one or more keys:
default(value: null to disable the default ShipStream-generated number or a string to override)invoice(value: string)purchase_order(value: string)rma(value: string){carrier_code}(e.g. "ups" or "fedex" - value: an object with carrier-specific reference number codes and strings as values)
Example
{
"reference_numbers": {
"default": "995-9253-451551",
"invoice": "I-430001"
}
}Shipping Accounts
You may override the Default Shipping Account Group configuration for an order using the shipping_account_group_id key. See Shipping Account Groups for more information on managing Shipping Account Groups.
shipping_account_group_id
The value of this key must be an integer representing the Group ID of a valid Shipping Account Group.
Example
{"shipping_account_group_id":5}Commercial Invoice Comments
The "Additional Comments" section of the Commercial Invoice as generated by FedEx and UPS may be manipulated using the commercial_invoice_comments key.
commercial_invoice_comments
The value of this key will appear on the generated Commercial Invoice where supported (FedEx and UPS).
The value may contain the following "placeholders" which will be replaced dynamically when the shipment is submitted:
{tax_number}- The export tax id number
Example
{"commercial_invoice_comments": "VAT has been collected at the point of sale via Tax ID #{tax_number}"}Duties Payor
The default International Duties and Taxes Payor may be configured for some carriers but you may also override the configuration for a given order using the duties_payor key.
duties_payor
The value of this key is one of the string values for shipper or recipient.
Example
{"duties_payor":"shipper"}Carbon Neutral
Currently only supported for UPS, you can set the carbon_neutral key to request UPS Carbon Neutral shipping.
carbon_neutral
The value of this key is a boolean (true or false).
Example
{"carbon_neutral":true}Delivery Instructions
The instructions key may be used to specify delivery instructions, if supported by the carrier. Currently only supported for FedEx.
instructions
The value of this key is a string. The maximum length is unknown.
Example
{"instructions":"Please leave at side door"}Export Compliance
If your shipment does not meet the requirements for the default EEI filing exemption (this is usually "30.37(a)") you may need to specify a custom Federal Trade Regulations (FTR) Exemption or Automated Export System (AES) Internal Transaction Number (ITN). You may use the export_compliance key to specify this information. This feature is currently only supported for FedEx and UPS and in both cases the shipper must either file the EEI electronically pre-departure or provide an FTR exemption.
See FedEx Electronic Export Information and UPS Electronic Export Information
export_compliance
The value of this field is an object with one of the keys: ftr_exemption or aes_itn and the value being a string containing the appropriate data.
Example for FTR Exemption
{"export_compliance":{"ftr_exemption":"30.37(f)"}}Example for AES ITN
{"export_compliance":{"aes_itn":"XXXXXX"}}FedEx Ground Collect
You can set the fedex_collect key to take advantage of the FedEx Ground Collect program. This program is not the same as C.O.D., but is a special program for commercial recipients to be billed directly for their inbound shipments. The recipient address must be specifically authorized to use this service or the charges will be billed to the shipper's account. Speak to your FedEx account representative about enabling this feature on your account. Also see "UPS Consignee Billing".
fedex_collect
The value of this key is a boolean (true or false).
Example
{"fedex_collect":true}FedEx One Rate
Take advantage of the FedEx One Rate program with the key fedex_one_rate. If the shipping method is a FedEx method the shipment will be validated against the FedEx One Rate program criteria and the online shipping request will specify the FedEx One Rate special service if eligible. There is no visible difference on the shipping label when One Rate pricing is applied.
fedex_one_rate
The value of this key is a boolean (true or false).
Example
{"fedex_one_rate":true}UPS Consignee Billing
You can set the consignee_billing key to take advantage of UPS Consignee Billing. Also see "FedEx Ground Collect".
consignee_billing
The value of this key is a boolean (true or false).
Example
{"consignee_billing":true}Custom Data
You can add custom data into Other Shipping Options, but unless it is documented here it may not have any effect. It is recommended to use a safe "namespace" to avoid conflicts with future officially supported features. For example, prefix the keys or use a single key with a nested object to store your custom data. All "Other Shipping Options" data including the custom data will be passed through to the External Shipping Methods API Endpoint URL verbatim.
Example
{
"acme": {
"option1": true
}
}