Shipment

Main shipment object containing all necessary data to create a shipment. Either parcel or parcels must be provided, but not both.

from_address
Type: object
required

Can be specified by ID or attributes to create a new one, and be verified inline. See Create an Address
- country
  Type: string
  required
  
  ISO 3166 country code for the country the address is located in
- state
  Type: string
  required
  
  State or province the address is located in
- zip
  Type: string
  required
  
  ZIP or postal code the address is located in
- city
  Type: string
  
  City the address is located in
- company
  Type: string | null
  
  Name of the organization. Both name and company can be included
- email
  Type: string | nullFormat: email
  
  Email to reach the person or organization
- name
  Type: string | null
  
  Name of the person. Both name and company can be included
- phone
  Type: string
  
  Phone number to reach the person or organization
- residential
  Type: boolean | null
  
  Whether or not this address would be considered residential
- street1
  Type: string
  
  First line of the address. Note: For U.S. and CA addresses, if street1 exceeds 35 characters, street2 is empty, and the end of street1 contains a recognized unit number format (e.g., “Apt 10”, or “Unit #99833”), the unit number is moved to street2
- street2
  Type: string
  
  Second line of the address. Note: May be automatically populated if a unit number is moved from street1 during address verification
to_address
Type: object
required

Can be specified by ID or attributes to create a new one, and be verified inline. See Create an Address
- country
  Type: string
  required
  
  ISO 3166 country code for the country the address is located in
- state
  Type: string
  required
  
  State or province the address is located in
- zip
  Type: string
  required
  
  ZIP or postal code the address is located in
- city
  Type: string
  
  City the address is located in
- company
  Type: string | null
  
  Name of the organization. Both name and company can be included
- email
  Type: string | nullFormat: email
  
  Email to reach the person or organization
- name
  Type: string | null
  
  Name of the person. Both name and company can be included
- phone
  Type: string
  
  Phone number to reach the person or organization
- residential
  Type: boolean | null
  
  Whether or not this address would be considered residential
- street1
  Type: string
  
  First line of the address. Note: For U.S. and CA addresses, if street1 exceeds 35 characters, street2 is empty, and the end of street1 contains a recognized unit number format (e.g., “Apt 10”, or “Unit #99833”), the unit number is moved to street2
- street2
  Type: string
  
  Second line of the address. Note: May be automatically populated if a unit number is moved from street1 during address verification
buyer_address
Type: object

The buyer's address, defaults to to_address
- country
  Type: string
  required
  
  ISO 3166 country code for the country the address is located in
- state
  Type: string
  required
  
  State or province the address is located in
- zip
  Type: string
  required
  
  ZIP or postal code the address is located in
- city
  Type: string
  
  City the address is located in
- company
  Type: string | null
  
  Name of the organization. Both name and company can be included
- email
  Type: string | nullFormat: email
  
  Email to reach the person or organization
- name
  Type: string | null
  
  Name of the person. Both name and company can be included
- phone
  Type: string
  
  Phone number to reach the person or organization
- residential
  Type: boolean | null
  
  Whether or not this address would be considered residential
- street1
  Type: string
  
  First line of the address. Note: For U.S. and CA addresses, if street1 exceeds 35 characters, street2 is empty, and the end of street1 contains a recognized unit number format (e.g., “Apt 10”, or “Unit #99833”), the unit number is moved to street2
- street2
  Type: string
  
  Second line of the address. Note: May be automatically populated if a unit number is moved from street1 during address verification
carrier
Type: string | null

Carrier to use for the shipment. If omitted along with carrier_accounts, all carriers are considered
carrier_accounts
Type: array string[] | null

List of CarrierAccount IDs
customs_info
Type: object

Information for processing the package through international customs
- contents_explanation
  Type: string
  
  Human readable description of content, max 255 characters. Required for certain carriers and always required if contents_type is 'other'
- contents_type
  Type: stringenum
  
  Possible values:
  
  values
  documents
  gift
  merchandise
  returned_goods
  sample
  dangerous_goods
  humanitarian_donation
  other
- customs_certify
  Type: boolean
  
  Electronically certify the information provided
- customs_items
  Type: array object[] · CustomsItem[]
  
  Describes products being shipped
  
  An item included in the shipment for customs declaration purposes
- customs_signer
  Type: string
  
  Required if customs_certify is true
- eel_pfc
  Type: string
  
  When shipping outside the US, you must provide either an Exemption and Exclusion Legend (EEL) code or a Proof of Filing Citation (PFC). Which one you need depends on the value of the goods:
  
  If the value is less than $2,500, pass the EEL code: NOEEI 30.37(a).
  
  If the value is greater than $2,500, you must obtain an Automated Export System (AES) Internal Transaction Number (ITN) from AESDirect, e.g. AES X20120502123456.
  
  An ITN is required for any international shipment valued over $2,500 and/or requiring an export license unless an exemption applies.
  
  Note: The maximum number of items that can be included in customs_info with UPS is 100
- id
  Type: string
  
  Unique, begins with 'cstinfo_'
- non_delivery_option
  Type: stringenum
  
  Possible values:
  
  values
  abandon
  return
- restriction_comments
  Type: string | null
  
  Required if restriction_type is not 'none'
- restriction_type
  Type: stringenum
  
  Possible values:
  
  values
  none
  quarantine
  sanitary_phytosanitary_inspection
  other
is_return
Type: boolean | null

Set true to create as a return shipment
options
Type: object | null

Additional shipment options. If carrier_accounts and service are set and options.create_and_buy is not explicitly false, it is treated as true.
- additional_handling
  Type: boolean | null
  
  Whether the package requires additional handling
- carbon_neutral
  Type: boolean | null
  
  Request carbon neutral delivery
- carrier_insurance_amount
  Type: number | null
  
  Declared insurance value for the carrier
- commercial_invoice_letterhead
  Type: string | null
  
  Header text for the commercial invoice
- commercial_invoice_signature
  Type: string | null
  
  Signature for the commercial invoice
- create_and_buy
  Type: boolean | null
  
  Immediately buy a label. Mutually exclusive with create_and_buy_cheapest
- create_and_buy_cheapest
  Type: boolean | null
  
  Automatically buy the cheapest rate. Mutually exclusive with create_and_buy
- delivery_confirmation
  Type: string | nullenum
  
  Delivery confirmation type
  
  values
  NO_SIGNATURE
  SIGNATURE
  SIGNATURE_RESTRICTED
  ADULT_SIGNATURE
  ADULT_SIGNATURE_RESTRICTED
- dropoff_max_datetime
  Type: string | nullFormat: date_time
  
  Latest acceptable drop-off time
- dropoff_type
  Type: string | null
  
  Dropoff type (e.g., REGULAR_PICKUP, SCHEDULED_PICKUP)
- duty_payment
  Type: object | null
  
  Duties/taxes billing information
- duty_payment_account
  Type: string | null
  
  Account ID to use for duty/tax payment
- endorsement
  Type: string | null
  
  Return instruction (e.g., RETURN_SERVICE_REQUESTED)
- fetch_express_delivery_date
  Type: boolean | null
  
  Request express delivery date from carrier
- hazmat
  Type: string | nullenum
  
  Indicates hazardous material
  
  values
  PRIMARY_CONTAINED
  PRIMARY_PACKED
  PRIMARY
  SECONDARY_CONTAINED
  SECONDARY_PACKED
- incoterm
  Type: string | null
  
  Incoterm for the shipment (e.g., DDP, DAP)
- is_return
  Type: boolean | null
  
  Indicates whether the shipment is a return
- label_date
  Type: string | nullFormat: date
  
  Date to appear on the shipping label
- label_format
  Type: string | null
  
  Label file format (e.g., PDF, ZPL)
- label_request_source
  Type: string | null
  
  Source of the label request (e.g., api)
- label_size
  Type: string | nullenum
  
  Label size (e.g., 4x6)
  
  values
  4x6
  8.5x11
  LETTER
- machinable
  Type: boolean | null
  
  Whether the parcel is machinable (USPS)
- parcels_response
  Type: boolean | null
  
  Whether to include parcels in the response
- payment
  Type: object | null
  
  Postage billing information
- pickup_max_datetime
  Type: string | nullFormat: date_time
  
  Latest acceptable pickup time
- pickup_min_datetime
  Type: string | nullFormat: date_time
  
  Earliest acceptable pickup time
- postage_label_inline
  Type: boolean | null
  
  Whether to return the label inline in the response
- print_custom
  Type: string | null
  
  Custom print field (carrier-specific)
- print_custom_1
  Type: string | null
  
  Custom print field 1
- print_custom_2
  Type: string | null
  
  Custom print field 2
- print_custom_3
  Type: string | null
  
  Custom print field 3
- saturday_delivery
  Type: boolean | null
  
  Request Saturday delivery
- special_rates_eligibility
  Type: string | null
  
  Special rate plan (e.g., usps.connect)
- suppress_etd
  Type: boolean | null
  
  Whether to suppress estimated delivery time
parcel
Type: object

The dimensions and weight of the package. Business rule: parcel and parcels MUST NOT both be present.
- height
  Type: number | null
  
  Height of the parcel (optional; must be sent with length + width if sent)
- id
  Type: string | null
  
  Unique parcel identifier (required if weight is not provided)
- items
  Type: array object[] | null · LineItem[]
  
  Line items inside the parcel
  
  Individual item contained within a parcel
- length
  Type: number | null
  
  Length of the parcel (optional; must be sent with width + height if sent)
- predefined_package
  Type: string | nullenum
  
  Carrier-specific predefined package type
  
  values
  CARD
  FEDEX10KGBOX
  FEDEX25KGBOX
  FEDEXENVELOPE
  FEDEXEXTRALARGEBOX
- weight
  Type: number | null
  
  Total package weight (required unless id is provided)
- width
  Type: number | null
  
  Width of the parcel (optional; must be sent with length + height if sent)
parcels
Type: array object[] | null · Parcel[]

Array of parcels. Business rule: parcel and parcels MUST NOT both be present.
The dimensions and weight of the package.

Rules (not enforced by JSON schema):

You may either: • Provide only id • OR omit id and provide weight (dimensions optional)

If any of length, width, or height is provided, all three must be provided.
- height
  Type: number | null
  
  Height of the parcel (optional; must be sent with length + width if sent)
- id
  Type: string | null
  
  Unique parcel identifier (required if weight is not provided)
- items
  Type: array object[] | null · LineItem[]
  
  Line items inside the parcel
  
  Individual item contained within a parcel
- length
  Type: number | null
  
  Length of the parcel (optional; must be sent with width + height if sent)
- predefined_package
  Type: string | nullenum
  
  Carrier-specific predefined package type
  
  values
  CARD
  FEDEX10KGBOX
  FEDEX25KGBOX
  FEDEXENVELOPE
  FEDEXEXTRALARGEBOX
- weight
  Type: number | null
  
  Total package weight (required unless id is provided)
- width
  Type: number | null
  
  Width of the parcel (optional; must be sent with length + height if sent)
reference
Type: string | null

An optional field that may be used in place of id in other API endpoints
return_address
Type: object

The shipper's address, defaults to from_address
- country
  Type: string
  required
  
  ISO 3166 country code for the country the address is located in
- state
  Type: string
  required
  
  State or province the address is located in
- zip
  Type: string
  required
  
  ZIP or postal code the address is located in
- city
  Type: string
  
  City the address is located in
- company
  Type: string | null
  
  Name of the organization. Both name and company can be included
- email
  Type: string | nullFormat: email
  
  Email to reach the person or organization
- name
  Type: string | null
  
  Name of the person. Both name and company can be included
- phone
  Type: string
  
  Phone number to reach the person or organization
- residential
  Type: boolean | null
  
  Whether or not this address would be considered residential
- street1
  Type: string
  
  First line of the address. Note: For U.S. and CA addresses, if street1 exceeds 35 characters, street2 is empty, and the end of street1 contains a recognized unit number format (e.g., “Apt 10”, or “Unit #99833”), the unit number is moved to street2
- street2
  Type: string
  
  Second line of the address. Note: May be automatically populated if a unit number is moved from street1 during address verification
service
Type: string | null

Requested service level (e.g., Priority, Express, GroundAdvantage)