Create a shipment

POST/shipping/{connection_id}/shipment

Parameters

fieldsstring array
Fields to return
rawstring
Raw parameters to include in the 3rd-party request. Encoded as a URL component. eg. raw parameters: foo=bar&zoo=bar -> raw=foo%3Dbar%26zoo%3Dbar
connection_idstring required
ID of the connection

Payload

idstring
Unique identifier for this shipment object
created_atdate-time
The date that this shipment object was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atdate-time
The last date that this shipment object was updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
order_idstring
Reference to commerce_order or accounting_order
organization_idstring
ref -> accounting Organization this shipment belongs to (multi-company ERPs)
from_addressobject
Origin address
to_addressobject
Destination address
packages array
Array of packages in this shipment
carrier_idstring
Reference to the carrier
service_codestring
Code for the shipping service used
status enum
Valid values:
"PENDING"
"PROCESSING"
"IN_TRANSIT"
"DELIVERED"
"EXCEPTION"
Current status of the shipment
rate_idstring
Optional reference to the selected rate (for traceability)
label_idstring
Optional reference to the shipping label
tracking_idstring
Optional reference to the tracking information
shipped_atdate-time
When shipment was createddispatched (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
rate_amountnumber
The rate amount used (may differ from shipping_cost due to adjustments)
rate_currencystring
Currency for rate_amount
rate_service_namestring
Service name from the rate (e.g., "Priority Mail")
rate_estimated_daysnumber
Estimated delivery days from the rate
rate_estimated_delivery_atdate-time
Estimated delivery date from the rate (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
is_rate_guaranteedboolean
Whether delivery is guaranteed (from rate)
return_addressobject
Return address (may differ from from_address)
return_authorization_numberstring
RMA number if return shipment
warehouse_location_idstring
Origin warehouselocation ID; points to CommerceLocation
warehouse_location_namestring
Origin warehouse location name
customsobject
Customs information
is_internationalboolean
Whether shipment is international
insuranceobject
Insurance details
special_instructionsstring array
Array of special instructions
is_signature_requiredboolean
Signature required on delivery
is_adult_signature_requiredboolean
Adult signature required
reference_numberstring
Customer reference number
is_returnboolean
Whether this is a return shipment
original_shipment_idstring
Reference to original shipment if return; points to ShippingShipment
return_reasonstring
Reason for return
return_type enum
Valid values:
"CUSTOMER"
"VENDOR"
"WARRANTY"
"DEFECTIVE"
"OTHER"
Type of return
carrier_namestring
Human-readable carrier/provider name when there is no carrier record to reference (e.g. commerce-platform fulfillments)
tracking_urlstring
Carrier tracking URL for this shipment
lineitems array
Item-level fulfillment lines (what shipped); used by commerce-platform fulfillments

Returns

Response fieldTypeRequiredDescription
idstringNoUnique identifier for this shipment object
created_atstring (date-time)NoThe date that this shipment object was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atstring (date-time)NoThe last date that this shipment object was updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
order_idstringNoReference to commerce_order or accounting_order
organization_idstringNoref -> accounting Organization this shipment belongs to (multi-company ERPs)
from_addressobjectNoOrigin address
from_address.address1stringNo
from_address.address2stringNo
from_address.citystringNo
from_address.regionstringNo
from_address.region_codestringNo
from_address.postal_codestringNo
from_address.countrystringNo
from_address.country_codestringNoISO 2-digit country code
from_address.namestringNoRecipientsender name
from_address.company_namestringNoCompany name (for commercial addresses)
from_address.telephonestringNoPhone number (required by FedEx, UPS, DHL)
from_address.emailstringNoEmail address (for delivery notifications)
from_address.is_residentialbooleanNoAlias for address_type === 'RESIDENTIAL'
from_address.is_validatedbooleanNoWhether address has been validated
from_address.delivery_instructionsstringNoSpecial delivery notes
to_addressobjectNoDestination address
to_address.address1stringNo
to_address.address2stringNo
to_address.citystringNo
to_address.regionstringNo
to_address.region_codestringNo
to_address.postal_codestringNo
to_address.countrystringNo
to_address.country_codestringNoISO 2-digit country code
to_address.namestringNoRecipientsender name
to_address.company_namestringNoCompany name (for commercial addresses)
to_address.telephonestringNoPhone number (required by FedEx, UPS, DHL)
to_address.emailstringNoEmail address (for delivery notifications)
to_address.is_residentialbooleanNoAlias for address_type === 'RESIDENTIAL'
to_address.is_validatedbooleanNoWhether address has been validated
to_address.delivery_instructionsstringNoSpecial delivery notes
packagesShippingPackage[]NoArray of packages in this shipment
packages[].weightnumberNoWeight of the package
packages[].weight_unitenumNoUnit for weight (g, kg, oz, lb) Values: g, kg, oz, lb
packages[].lengthnumberNoLength of the package
packages[].widthnumberNoWidth of the package
packages[].heightnumberNoHeight of the package
packages[].size_unitenumNoUnit for dimensions (cm, inch) Values: cm, inch
packages[].descriptionstringNoDescription of the package contents
packages[].valuenumberNoDeclared value of the package
packages[].currencystringNoISO 4217 currency code
packages[].tracking_numberstringNoPackage-level tracking (for multi-package shipments)
packages[].insured_amountnumberNoInsured value for this package
carrier_idstringNoReference to the carrier
service_codestringNoCode for the shipping service used
statusenumNoCurrent status of the shipment Values: PENDING, PROCESSING, IN_TRANSIT, DELIVERED, EXCEPTION, CANCELLED, LABEL_CREATED, PICKED_UP, OUT_FOR_DELIVERY, DELIVERY_ATTEMPTED, RETURNED_TO_SENDER, HELD_AT_LOCATION, CUSTOMS_CLEARANCE, EXCEPTION_RESOLVED
rate_idstringNoOptional reference to the selected rate (for traceability)
label_idstringNoOptional reference to the shipping label
tracking_idstringNoOptional reference to the tracking information
shipped_atstring (date-time)NoWhen shipment was createddispatched (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
rate_amountnumberNoThe rate amount used (may differ from shipping_cost due to adjustments)
rate_currencystringNoCurrency for rate_amount
rate_service_namestringNoService name from the rate (e.g., "Priority Mail")
rate_estimated_daysnumberNoEstimated delivery days from the rate
rate_estimated_delivery_atstring (date-time)NoEstimated delivery date from the rate (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
is_rate_guaranteedbooleanNoWhether delivery is guaranteed (from rate)
return_addressobjectNoReturn address (may differ from from_address)
return_address.address1stringNo
return_address.address2stringNo
return_address.citystringNo
return_address.regionstringNo
return_address.region_codestringNo
return_address.postal_codestringNo
return_address.countrystringNo
return_address.country_codestringNoISO 2-digit country code
return_address.namestringNoRecipientsender name
return_address.company_namestringNoCompany name (for commercial addresses)
return_address.telephonestringNoPhone number (required by FedEx, UPS, DHL)
return_address.emailstringNoEmail address (for delivery notifications)
return_address.is_residentialbooleanNoAlias for address_type === 'RESIDENTIAL'
return_address.is_validatedbooleanNoWhether address has been validated
return_address.delivery_instructionsstringNoSpecial delivery notes
return_authorization_numberstringNoRMA number if return shipment
warehouse_location_idstringNoOrigin warehouselocation ID; points to CommerceLocation
warehouse_location_namestringNoOrigin warehouse location name
customsobjectNoCustoms information
customs.contents_typeenumNoValues: MERCHANDISE, DOCUMENTS, GIFT, RETURNED_GOODS, SAMPLE, OTHER
customs.descriptionstringNoExplanation of contents
customs.amountnumberNoCustoms declared value
customs.currencystringNo
customs.duties_paid_byenumNoValues: SENDER, RECIPIENT, THIRD_PARTY
customs.taxes_paid_byenumNoValues: SENDER, RECIPIENT, THIRD_PARTY
customs.shipper_eoristringNoExporter EORI number
customs.recipient_eoristringNoImporter EORI number
customs.shipper_tax_numberstringNoExporter tax ID
customs.recipient_tax_numberstringNoImporter tax ID
customs.itemsShippingCustomsItem[]NoCustoms items
customs.items[].descriptionstringNoItem description
customs.items[].quantitynumberNoQuantity
customs.items[].amountnumberNoValue per unit
customs.items[].currencystringNo
customs.items[].weightnumberNoWeight per unit
customs.items[].weight_unitenumNoValues: g, kg, oz, lb
customs.items[].harmonized_tariff_codestringNoHS code
customs.items[].country_of_originstringNoCountry of origin (ISO code)
customs.items[].skustringNoSKU
customs.restrictionsstring[]NoAny restrictions
customs.non_delivery_optionenumNoValues: RETURN, ABANDON
is_internationalbooleanNoWhether shipment is international
insuranceobjectNoInsurance details
insurance.insured_valuenumberNoInsured value
insurance.currencystringNo
insurance.insurance_providerstringNoInsurance provider name
insurance.insurance_provider_codestringNoProvider code
insurance.insurance_costnumberNoCost of insurance
insurance.insurance_cost_currencystringNo
insurance.coverage_typeenumNoValues: STANDARD, PREMIUM, CUSTOM
insurance.coverage_amountnumberNoCoverage amount (may differ from insured_value)
special_instructionsstring[]NoArray of special instructions
is_signature_requiredbooleanNoSignature required on delivery
is_adult_signature_requiredbooleanNoAdult signature required
reference_numberstringNoCustomer reference number
is_returnbooleanNoWhether this is a return shipment
original_shipment_idstringNoReference to original shipment if return; points to ShippingShipment
return_reasonstringNoReason for return
return_typeenumNoType of return Values: CUSTOMER, VENDOR, WARRANTY, DEFECTIVE, OTHER
carrier_namestringNoHuman-readable carrier/provider name when there is no carrier record to reference (e.g. commerce-platform fulfillments)
tracking_urlstringNoCarrier tracking URL for this shipment
lineitemsShippingShipmentLineitem[]NoItem-level fulfillment lines (what shipped); used by commerce-platform fulfillments
lineitems[].idstringNoUnique identifier for this fulfillment line
lineitems[].item_idstringNoReference to the CommerceItem being fulfilled (reference to CommerceItem)
lineitems[].item_variant_idstringNoReference to the CommerceItemvariant being fulfilled (reference to CommerceCommerceItemvariant)
lineitems[].order_lineitem_idstringNoThe order line being fulfilled
lineitems[].quantitynumberNoUnits fulfilled on this line
lineitems[].item_namestringNoItem name (for display)
lineitems[].skustringNoItem SKU

Errors

Errors return the HTTP status code and a JSON body with statusCode, error (the short label) and message (a human-readable detail).

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests to unified.to API; max requests per minute: N"
}
StatusErrorMeaning
400Bad RequestThe request was malformed or failed validation.
401UnauthorizedThe connection is likely broken; re-authorize it.
403ForbiddenThe connection is missing permissions or scopes.
404Not FoundThe requested resource does not exist.
429Too Many RequestsRate limit exceeded (see the two sources below).
500Internal Server ErrorAn unexpected error occurred.
501Not ImplementedNot supported by this integration.

Errors from the underlying integration pass through: the integration's status comes back as ours (429, 401, 403, 404 or 5xx), usually with its message. When the integration's error body is unclear, Unified extracts what it can and returns a clearer message.

429 Too Many Requests

A 429 has two possible sources:

  • The integration's own rate limit, passed through.
  • Unified's workspace limit: a rolling 60 seconds, set by plan, with the message Too many requests to unified.to API; max requests per minute: N.
const options = {
  method: 'POST',
  url: 'https://api.unified.to/shipping/5de520f96e439b002043d8dc/shipment',
  headers: {
    authorization: 'bearer .....'
  },
  data: undefined,
  params: {
    fields: '',
    raw: '',
  }
};

const results = await axios.request(options);
Are we missing anything? Let us know
Was this page helpful?