Shipments

Shipment Model

Properties

  • Name
    id
    Type
    string
    Restrictions
    Description

    The unique ID for the shipment

  • Name
    addresses
    Type
    object
    Restrictions
    Description
  • Name
    » destination
    Type
    [Address](#schemaaddress)
    Required
    required
    Restrictions
    Description

    The destination address for the shipment. This is usually the customers address.

  • Name
    » origin
    Type
    [Address](#schemaaddress)
    Required
    required
    Restrictions
    Description

    The address where the shipment is being sent from. This is usually the fulfilment warehouse.

  • Name
    » return
    Type
    [Address](#schemaaddress)
    Restrictions
    Description

    In the event of a returned shipment, the address to where the shipment will be returned. This is usually the same as the origin address.

  • Name
    » location_configuration_id
    Type
    string,null
    Restrictions
    Description

    A location configuration ID that will be used to populate saved address data for

  • Name
    tax_identifiers
    Type
    [[ShipmentTaxIdentifier](#schemashipmenttaxidentifier)]
    Restrictions
    Description
  • Name
    packages
    Type
    [[ShipmentPackage](#schemashipmentpackage)]
    Restrictions
    Description

    An array containing the packages that form the shipment.

    For shipments with multiple packages, only certain carriers and services support multi package shipments, others require one package per shipment.

    There is a limit of 20 packages per shipment. If this does not fit your needs, please contact us to discuss the use case further.

  • Name
    customs
    Type
    [CustomsDetail](#schemacustomsdetail)
    Restrictions
    Description
  • Name
    options
    Type
    [ShipmentOptions](#schemashipmentoptions)
    Restrictions
    Description
  • Name
    carrier
    Type
    [ShipmentCarrier](#schemashipmentcarrier)
    Restrictions
    Description
  • Name
    name
    Type
    string,null
    Restrictions
    Description

    A name for the shipment, used for easy identification.

  • Name
    documents
    Type
    array,null
    Restrictions
    Description

    An array of documents such as labels and commercial invoices attached to the shipment.

  • Name
    rates
    Type
    array,null
    Restrictions
    Description

    An array of rates available to the current shipment.

  • Name
    service
    Type
    [ShipmentService](#schemashipmentservice)
    Restrictions
    Description

    The shipment service that is selected when the shipment is finalised.

  • Name
    status
    Type
    string,null
    Restrictions
    Description

    The current status of the shipment.

  • Name
    created_at
    Type
    string,null(date-time)
    Description
  • Name
    updated_at
    Type
    string,null(date-time)
    Description
  • Name
    errors
    Type
    array,null
    Restrictions
    Description

    Any errors that occur during the creation or finalisation of the shipment.

{
  "id": "shp_0ujzPyRiIAffKhBux4PvQdDqMHY",
  "addresses": {
    "destination": {
      "address": {
        "line_1": "29 Holgate Rd",
        "line_2": "Segwick Street",
        "line_3": "Kelvedon",
        "city": "RACKWICK",
        "province": "Cambershire",
        "post_code": "KW16 2PE",
        "country_code": "GB"
      },
      "contact": {
        "name": "Francesca Brady",
        "company": "Malvinex Corp"
      },
      "display_name": "Work",
      "metadata": {
        "contact_email": "[email protected]"
      },
      "marketplaces": {
        "shopify": "657847832011"
      },
      "coordinates": {
        "latitude": 51.5134297,
        "longitude": -0.103145,
        "confidence": 1
      }
    },
    "origin": {
      "address": {
        "line_1": "29 Holgate Rd",
        "line_2": "Segwick Street",
        "line_3": "Kelvedon",
        "city": "RACKWICK",
        "province": "Cambershire",
        "post_code": "KW16 2PE",
        "country_code": "GB"
      },
      "contact": {
        "name": "Francesca Brady",
        "company": "Malvinex Corp"
      },
      "display_name": "Work",
      "metadata": {
        "contact_email": "[email protected]"
      },
      "marketplaces": {
        "shopify": "657847832011"
      },
      "coordinates": {
        "latitude": 51.5134297,
        "longitude": -0.103145,
        "confidence": 1
      }
    },
    "return": {
      "address": {
        "line_1": "29 Holgate Rd",
        "line_2": "Segwick Street",
        "line_3": "Kelvedon",
        "city": "RACKWICK",
        "province": "Cambershire",
        "post_code": "KW16 2PE",
        "country_code": "GB"
      },
      "contact": {
        "name": "Francesca Brady",
        "company": "Malvinex Corp"
      },
      "display_name": "Work",
      "metadata": {
        "contact_email": "[email protected]"
      },
      "marketplaces": {
        "shopify": "657847832011"
      },
      "coordinates": {
        "latitude": 51.5134297,
        "longitude": -0.103145,
        "confidence": 1
      }
    },
    "location_configuration_id": "lc_2iFuzwcptRh9xt93ICDzK0vOszc"
  },
  "tax_identifiers": [
    {
      "taxable_entity_type": "sender",
      "identifier_type": "ioss",
      "value": "IM0123456789",
      "issuing_country_code": "string"
    }
  ],
  "packages": [
    {
      "name": "string",
      "geometry": {
        "length": 0,
        "width": 0,
        "height": 0,
        "mass": 0
      },
      "predefined_package_code": "string"
    }
  ],
  "customs": {
    "contents_type": "merchandise",
    "contents_description": "automobile parts",
    "declarant": {
      "name": "string",
      "certify": true,
      "date": "string"
    },
    "incoterm": "DDP",
    "restriction_type": "other",
    "restriction_description": "string",
    "declaration_message": "string",
    "items": null,
    "identifiers": [
      {
        "entity_type": "import",
        "identifier_type": "license",
        "value": "string",
        "issuing_country_code": "string"
      }
    ]
  },
  "options": {
    "shipping": {
      "access_code": "473281",
      "commercial_address": false,
      "currency_code": "USD",
      "date": "2022-07-11T00:00:00.00Z",
      "delivery_confirmation": false,
      "dry_ice_mass": 2500,
      "dropoff_type": "regular_pickup",
      "handling_instructions": "Leave behind plant pot in front porch.",
      "high_security": true,
      "hold_for_pickup": false,
      "invalid_address_handling": "forward_or_return",
      "is_return": false,
      "leave_safe": true,
      "machinable": true,
      "non_delivery": "return",
      "restricted_substances": [
        "alcohol"
      ],
      "safe_place": "Garden Shed",
      "saturday_delivery": false,
      "signature_required": true,
      "signature_type": "standard",
      "tracked_service": true
    },
    "label": {
      "format": "pdf",
      "size": "4x6",
      "custom_data": {
        "text_lines": {
          "line_1": null,
          "line_2": null,
          "line_3": null
        },
        "line_codes": {
          "line_1": null,
          "line_2": null,
          "line_3": null
        },
        "barcodes": {
          "barcode_1": null,
          "barcode_2": null,
          "barcode_3": null
        }
      }
    },
    "insurance": {
      "value": 55000,
      "currency_code": "USD"
    }
  },
  "carrier": {
    "carrier_code": "string",
    "service_code": "string",
    "carrier_accounts": [
      "string"
    ]
  },
  "name": "ORDER-273548",
  "documents": [
    {
      "id": "doc_2iBgUNtezju7lmzmfOoJO8cnsVS",
      "type": "label",
      "file_name": "2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png",
      "file_type": "image/png",
      "file_size": 129842,
      "file_url": "https://envoy-shipment-files.s3.amazonaws.com/labels/2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png?AWSAccessKeyId=AKIAY27LA84LC8DHB20X&Signature=kZY1RHl%2BBIClJ0UpjpKtAeqZqJA%3D&Expires=1725464510",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "rates": [
    {
      "id": "string",
      "carrier": {
        "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
        "name": "UPS",
        "handle": "ups"
      },
      "carrier_service": {
        "id": "cs_2iBgUNbKrgj7uVrsSiiF5ZhTelp",
        "name": "Express",
        "handle": "express"
      },
      "carrier_account": null,
      "rate": 1650,
      "currency_code": "USD",
      "delivery_days": 3,
      "ship_date": "2024-06-18T14:15:22Z",
      "delivery_date": "2024-06-21T14:15:22Z",
      "guaranteed_delivery_date": "2024-06-22T14:15:22Z"
    }
  ],
  "service": {
    "rate": "rate_2iBgUKWHmQlBjYQyx9fAGMvcCEp",
    "carrier": {
      "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "UPS",
      "handle": "ups"
    },
    "carrier_service": {
      "id": "cs_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "Express",
      "handle": "express"
    },
    "carrier_account": {
      "id": "ca_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "Main Account",
      "handle": null
    }
  },
  "status": "purchased",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "errors": [
    {
      "type": "rate_error",
      "code": "rates_unavailable",
      "source": "provider",
      "message": "rates are not available for the provided shipment"
    }
  ]
}

Shipment Carrier Model

Properties

  • Name
    carrier_code
    Type
    string,null
    Restrictions
    Description

    The carrier code if the shipment should be sent with a specific carrier.

  • Name
    service_code
    Type
    string,null
    Restrictions
    Description

    The service code for the carrier shipment service. Only used if the carrier_code field is set.

  • Name
    carrier_accounts
    Type
    array,null
    Restrictions
    Description

    If shipments should only be sent using certain carriers, this field can be used to pass an array of carrier accounts that can be used to send the shipment.

{
  "carrier_code": "string",
  "service_code": "string",
  "carrier_accounts": [
    "string"
  ]
}

Shipment Options Model

Properties

  • Name
    shipping
    Type
    object,null
    Restrictions
    Description

    Options relating to the shipment contents and service.

  • Name
    » access_code
    Type
    string,null
    Restrictions
    Description

    If specified, an access code for use at the destination address.

  • Name
    » commercial_address
    Type
    boolean,null
    Restrictions
    Description

    Indicates if the address is a commerical address.

    Assumed to be residential if unset or set to false.

    In some cases, marking the address as commercial can result in cheaper rates, though incorrectly marked addresses may incur a surcharge.

  • Name
    » currency_code
    Type
    string,null
    Restrictions
    Description

    The 3 letter currency code that rates should be returned in. Only supported with some carriers.

    Defaults to USD if unspecified.

  • Name
    » date
    Type
    string,null(date-time)
    Restrictions
    Description

    The RFC 3339 formatted date for when the shipment is due to be collected by the carrier.

  • Name
    » delivery_confirmation
    Type
    boolean,null
    Restrictions
    Description

    Requests delivery confirmation for the shipment. May incur additional fees.

  • Name
    » dry_ice_mass
    Type
    integer,null
    Restrictions
    Description

    In the event that the shipment contains dry ice, this field must include the weight of dry ice in the shipment, in grams.

    Required if the restricted_substances field contains either the dry_ice or dry_ice_medical flags.

    Dry ice is only supported by some carriers.

  • Name
    » dropoff_type
    Type
    string,null
    Restrictions
    Description

    How the parcel will be dropped off with the carrier.

    This is typically handled by a regular pickup by the carrier from the merchant.

    Possible Enum Values

    regular_pickup
    scheduled_pickup
    dropbox_location
    retail_location
  • Name
    » handling_instructions
    Type
    string,null
    Restrictions
    Description

    Instructions to the driver for delivering the parcel.

    Not supported by all carriers. Some carriers may have limits on the number of characters. Messages exceeding the maximum length may be omitted or only partially printed.

  • Name
    » high_security
    Type
    boolean,null
    Restrictions
    Description

    Indicates that the shipment should use a high security service.

    Only supported by certain carriers, usually an additional surcharge is applicable.

  • Name
    » hold_for_pickup
    Type
    boolean,null
    Restrictions
    Description

    Indicates that the package should be detained at the destination depot for collection by the recipient.

  • Name
    » invalid_address_handling
    Type
    string,null
    Restrictions
    Description

    Determines how a shipment is handled when the destination address is undeliverable, possibly due to the recipient having moved. The possible values are as follows:

    - notify_and_discard: The merchant receives a notification of the recipient's new address if a forwarding address has been provided. The shipment is not returned or delivered.

    - forward_or_return: The same as notify_and_discard, except that instead of discarding the shipment, it is forwarded to the new address, or returned to the merchant if forwarding is not possible. This may incur an additional fee.

    - return: The package is returned to the merchant if delivery fails. This may incur an additional fee.

    - temp_return: If the change of address is temporary, the package is forwarded to the temporary address and the merchant is not notified of the new address. Otherwise shipment is returned to merchant with new address.

    Possible Enum Values

    notify_and_discard
    forward_or_return
    return
    temp_return
  • Name
    » is_return
    Type
    boolean,null
    Restrictions
    Description

    Whether the shipment is a returns shipment (ie. from customer to merchant). This may incur additional fees.

  • Name
    » leave_safe
    Type
    boolean,null
    Restrictions
    Description

    Indicates that the carrier can leave the parcel safe.

  • Name
    » machinable
    Type
    boolean,null
    Restrictions
    Description

    Indicates that the shipment is suitable for handling by automated sorting equipment.

    Each carrier has slightly different criteria for what constitutes a machinable parcel, you will need to be aware of your chosen carrier's requirements before shipping parcels with them.

    Non-machinable parcels may incur an additional fee.

  • Name
    » non_delivery
    Type
    string,null
    Restrictions
    Description

    Whether a shipment should be abandoned or returned if it cannot be delivered.

    This setting also applies to customs - if a shipment is unable to clear customs, setting this to abandon will result in the shipment being disposed of, whilst return will result in it being returned to the merchant.

    Either option may incur additional fees depending on the carrier.

    N.B. If set, the invalid_address_handling field takes precedent for supported carriers. In this case, this field will be used as the fallback behaviour.

    Possible Enum Values

    abandon
    return
  • Name
    » restricted_substances
    Type
    array,null
    Restrictions
    Description

    An array of identifiers for any restricted substances contained in the shipment.

    You will need to ensure that your chosen carrier permits the carriage of any restricted substances you specify, as failure to do so may result in unforeseen fees or penalties.

    Depending on the substance, additional fees may by incurred.

  • Name
    » safe_place
    Type
    string,null
    Restrictions
    Description

    A short descriptor for the preferred safe place, eg. garage, garden shed, storage box, etc.

  • Name
    » saturday_delivery
    Type
    boolean,null
    Restrictions
    Description

    Indicates that the shipment should be sent using a service that includes Saturday delivery.

  • Name
    » signature_required
    Type
    boolean,null
    Restrictions
    Description

    Indicates that a signature is required.

  • Name
    » signature_type
    Type
    string,null
    Restrictions
    Description

    The type of signature required. Requesting the type of signature is only supported by some carriers.

    The following values are valid:

    - standard: The shipment can be signed for by a person residing at the address specified on the label.

    - standard_restricted: The shipment can be signed for only by the person named on the shipping label.

    - indirect: The shipment can be signed for by a person at or living near to the address proviced on the label.

    - adult: The shipment can be signed ffor by an adult residing at the address specified on the label.

    - adult_restricted: The shipment can be signed for only by the adult named on the shipping label.

    N.B. When sending with certain carriers, such as USPS, an adult signature is deemed to be a person of 21 years or older. A person between 18-20 years old is unable to sign for such packages.

    Possible Enum Values

    standard
    standard_restricted
    indirect
    adult
    adult_restricted
  • Name
    » tracked_service
    Type
    boolean,null
    Restrictions
    Description

    Indicates that the shipment should be sent using a tracked service.

  • Name
    label
    Type
    object,null
    Restrictions
    Description

    Options relating to the physical shipping label.

  • Name
    » format
    Type
    string,null
    Restrictions
    Description

    The format that the label is returned in.

    Not all formats are supported by all carriers. If the requested format is not supported, the available format will be returned.

    Possible Enum Values

    pdf
    png
    zpl
  • Name
    » size
    Type
    string,null
    Restrictions
    Description

    THe size of the returned label.

    Carriers return labels in varying sizes. Any size supplied here must be accepted by the carrier, otherwise it will either be ignored when generating the label, or return an error.

    Possible Enum Values

    4x4
    4x5
    4x6
    4x7
    4x8
    8.5x11
  • Name
    » custom_data
    Type
    object,null
    Restrictions
    Description

    For any custom information that the merchant wishes to print on the label.

    Not supported by all carriers.

  • Name
    » text_lines
    Type
    object,null
    Restrictions
    Description

    Plain text lines that will be printed on the label.

    If less than 3 lines is supported, the available lines will be printed.

  • Name
    » line_1
    Type
    string,null
    Restrictions
    Description
  • Name
    » line_2
    Type
    string,null
    Restrictions
    Description
  • Name
    » line_3
    Type
    string,null
    Restrictions
    Description
  • Name
    » line_codes
    Type
    object,null
    Restrictions
    Description

    Certain carriers, such as USPS, display the lines in the format: key: value. For carriers that support this, the key can either be specified, or must be one of a set of predefined codes.

    Set these fields to determine the value for key as printed on the label. The contents of text_lines is used for the value part.

  • Name
    » line_1
    Type
    string,null
    Restrictions
    Description
  • Name
    » line_2
    Type
    string,null
    Restrictions
    Description
  • Name
    » line_3
    Type
    string,null
    Restrictions
    Description
  • Name
    » barcodes
    Type
    object,null
    Restrictions
    Description

    If the carrier supports user-defined barcodes on the label, the data for the barcodes can be passed here.

    We recommend keeping this data to numeric only if possible, or alphanumeric if necessary, to ensure maximum compatibility with supported barcode formats.

  • Name
    » barcode_1
    Type
    string,null
    Restrictions
    Description
  • Name
    » barcode_2
    Type
    string,null
    Restrictions
    Description
  • Name
    » barcode_3
    Type
    string,null
    Restrictions
    Description
  • Name
    insurance
    Type
    object,null
    Restrictions
    Description

    Options for supplying insurance related data.

  • Name
    » value
    Type
    integer,null
    Restrictions
    Description

    The value of insurance requested, in the smallest unit of the specified currency.

    The insurance requested here should not exceed the value of the items declared in the customs section.

    If no currency code is specified, defaults to USD.

  • Name
    » currency_code
    Type
    string,null
    Restrictions
    Description

    The 3-letter currency code that the insurance value is represented in.

    Defaults to USD if unspecified.

{
  "shipping": {
    "access_code": "473281",
    "commercial_address": false,
    "currency_code": "USD",
    "date": "2022-07-11T00:00:00.00Z",
    "delivery_confirmation": false,
    "dry_ice_mass": 2500,
    "dropoff_type": "regular_pickup",
    "handling_instructions": "Leave behind plant pot in front porch.",
    "high_security": true,
    "hold_for_pickup": false,
    "invalid_address_handling": "forward_or_return",
    "is_return": false,
    "leave_safe": true,
    "machinable": true,
    "non_delivery": "return",
    "restricted_substances": [
      "alcohol"
    ],
    "safe_place": "Garden Shed",
    "saturday_delivery": false,
    "signature_required": true,
    "signature_type": "standard",
    "tracked_service": true
  },
  "label": {
    "format": "pdf",
    "size": "4x6",
    "custom_data": {
      "text_lines": {
        "line_1": "string",
        "line_2": "string",
        "line_3": "string"
      },
      "line_codes": {
        "line_1": "string",
        "line_2": "string",
        "line_3": "string"
      },
      "barcodes": {
        "barcode_1": "string",
        "barcode_2": "string",
        "barcode_3": "string"
      }
    }
  },
  "insurance": {
    "value": 55000,
    "currency_code": "USD"
  }
}

Shipment Package Model

Properties

  • Name
    name
    Type
    string,null
    Restrictions
    Description

    A name/reference for the package.

  • Name
    geometry
    Type
    object
    Restrictions
    Description
  • Name
    » length
    Type
    integer,null
    Restrictions
    Description

    The length of the package, in millimetres

  • Name
    » width
    Type
    integer,null
    Restrictions
    Description

    The width of the package, in millimetres

  • Name
    » height
    Type
    integer,null
    Restrictions
    Description

    The height of the package, in millimetres

  • Name
    » mass
    Type
    integer
    Restrictions
    Description

    The mass (weight) of the package, in grams

  • Name
    predefined_package_code
    Type
    string,null
    Restrictions
    Description

    For carriers with predefined package sizes or packaging materials, specify the code here.

    For some carriers, predefined packages may be eligible for cheaper rates.

{
  "name": "string",
  "geometry": {
    "length": 0,
    "width": 0,
    "height": 0,
    "mass": 0
  },
  "predefined_package_code": "string"
}

Shipment Tax Identifier Model

Properties

  • Name
    taxable_entity_type
    Type
    string,null
    Restrictions
    Description

    The entity that this tax identifier is tied to. One of: shipper, receiver

    Possible Enum Values

    receiver
    sender
  • Name
    identifier_type
    Type
    string
    Restrictions
    Description

    The type of tax identifier provided.

    The possible identifier types are:

    - vat: Value Added Tax
    - ssn: Social Security Number
    - ioss: Import One Stop Shop
    - gst: Goods & Services Tax
    - eori: Economic Operators Registration & Identification
    - pan: Permanent Account Number
    - ftz: Foreign Trade Zone
    - dan: Deferment Account Number (Duties Only)
    - dtf: Deferment Account Number (Duties, Taxes & Fees)
    - tan: Deferment Account Number (Tax Only)
    - duns: Data Universal Numbering System (Dun & Bradstreet)
    - ein: (Federal) Employer Identification Number
    - fed: Federal Tax ID (other than EIN)
    - sta: State Tax ID
    - tin: Taxpayer Identification Number
    - voec: VAT on E-Commerce (Norway only)
    - cnpj: Cadastro Nacional da Pessoa Jurídica

    Possible Enum Values

    vat
    dan
    dtf
    duns
    ioss
    ein
    eori
    fed
    ftz
    gst
    pan
    ssn
    tan
    tin
    cnpj
    voec
    sta
  • Name
    value
    Type
    string
    Restrictions
    Description

    The tax identifier itself.

  • Name
    issuing_country_code
    Type
    string,null
    Restrictions
    Description

    The 2-letter country code for the tax identifier issuing authority.

{
  "taxable_entity_type": "sender",
  "identifier_type": "ioss",
  "value": "IM0123456789",
  "issuing_country_code": "string"
}

Manifest Model

Properties

  • Name
    id
    Type
    string,null
    Restrictions
    Description

    The unique ID for the manifest.

  • Name
    carrier
    Type
    [CarrierResource](#schemacarrierresource)
    Restrictions
    Description

    The associated carrier for the manifest.

  • Name
    status
    Type
    string,null
    Restrictions
    Description

    The status of the manifest, one of creating, created or failed.

  • Name
    messages
    Type
    array,null
    Restrictions
    Description

    An array of messages that may indicate manifest status or errors.

  • Name
    documents
    Type
    array,null
    Restrictions
    Description

    An array of documents that are associates with the manifest.

  • Name
    shipments
    Type
    array,null
    Restrictions
    Description

    An array of the shipment IDs included in the manifest.

{
  "id": "mfst_2iEunM6YPs9Y9MUILsx4g4fA8rw",
  "carrier": {
    "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
    "name": "UPS",
    "handle": "ups",
    "description": "United Parcel Service"
  },
  "status": "created",
  "messages": [
    "string"
  ],
  "documents": [
    {
      "id": "doc_2iBgUNtezju7lmzmfOoJO8cnsVS",
      "type": "label",
      "file_name": "2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png",
      "file_type": "image/png",
      "file_size": 129842,
      "file_url": "https://envoy-shipment-files.s3.amazonaws.com/labels/2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png?AWSAccessKeyId=AKIAY27LA84LC8DHB20X&Signature=kZY1RHl%2BBIClJ0UpjpKtAeqZqJA%3D&Expires=1725464510",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "shipments": [
    "shp_2iEunS09o0T6HGm41Fz32VNBcqX"
  ]
}

Customs Detail Model

Properties

  • Name
    contents_type
    Type
    string,null
    Restrictions
    Description

    The type of goods contained within the shipment and their intended purpose.

    One of:

    - merchandise
    - documents
    - gift
    - returned_goods
    - commercial_sample
    - other

    Possible Enum Values

    documents
    gift
    merchandise
    returned_goods
    other
    commercial_sample
  • Name
    contents_description
    Type
    string,null
    Restrictions
    Description

    A short description of the contents of the shipment, eg. "automobile parts".

    Required by certain carriers, and always of the contents_type is set to other.

  • Name
    declarant
    Type
    object,null
    Restrictions
    Description
  • Name
    » name
    Type
    string
    Restrictions
    Description

    The name (first and last) of the individual making the customs declaration.

    Defaults to the contact name for the origin address if not supplied.

  • Name
    » certify
    Type
    boolean
    Restrictions
    Description

    Indicates that the declarant affirms that all information supplied is accurate and valid.

    Failure to set this parameter explicitly to true may result in customs delays, or failure to create the shipment.

  • Name
    » date
    Type
    string,null
    Restrictions
    Description

    The date for the declaration. Defaults to the current date if not supplied.

  • Name
    incoterm
    Type
    string,null
    Restrictions
    Description

    A code for the incoterm that applies to this shipment.

    The details for the available incoterm codes and what they mean are available at: https://www.trade.gov/know-your-incoterms

    Any incoterm passed should be lowercased.

    Possible Enum Values

    EXW
    FCA
    CPT
    CIP
    DAP
    DPU
    DDP
    FAS
    FOB
    CFR
    CIF
  • Name
    restriction_type
    Type
    string,null
    Restrictions
    Description

    If necessary, the type of restriction applicable to the shipment. One of:

    - none
    - other
    - quarantine
    - sanitary_phytosanitary_inspection

    Possible Enum Values

    none
    other
    quarantine
    sanitary_phytosanitary_inspection
  • Name
    restriction_description
    Type
    string,null
    Restrictions
    Description

    For any value other than none in the restriction_type field, this is required.

    A short description detailing the reason for the restriction.

  • Name
    declaration_message
    Type
    string,null
    Restrictions
    Description

    A message to accompany the customs declaration.

    Only certain carriers support this, and some require it.

  • Name
    items
    Type
    null,array
    Restrictions
    Description

    Product entries to be included on the customs declaration.

    These should be provided wherever possible, as the items listed here are also used in the event of an insurance claim being made.

  • Name
    identifiers
    Type
    array,null
    Restrictions
    Description

    An array of customs identifiers associated with the shipment.

{
  "contents_type": "merchandise",
  "contents_description": "automobile parts",
  "declarant": {
    "name": "string",
    "certify": true,
    "date": "string"
  },
  "incoterm": "DDP",
  "restriction_type": "other",
  "restriction_description": "string",
  "declaration_message": "string",
  "items": null,
  "identifiers": [
    {
      "entity_type": "import",
      "identifier_type": "license",
      "value": "string",
      "issuing_country_code": "string"
    }
  ]
}

Customs Item Model

Properties

  • Name
    description
    Type
    string
    Restrictions
    Description

    A short description of the item in the shipment.

  • Name
    quantity
    Type
    integer
    Restrictions
    Description

    The quantity of the item present in the shipment.

  • Name
    value
    Type
    integer
    Restrictions
    Description

    The unit value of the item in the smallest currency unit of the specified currency.

  • Name
    currency_code
    Type
    string,null
    Restrictions
    Description

    The 3-letter currency code that the value is represented in.

    Defaults to USD if not provided.

  • Name
    mass
    Type
    integer,null
    Restrictions
    Description

    The mass (weight) of the items, in grams.

  • Name
    product_identifier
    Type
    string,null
    Restrictions
    Description

    A product identifier that the merchant can provide to reference the item on their own system. This should be an SKU/UPC/GTIN/etc.

  • Name
    hs_tariff_code
    Type
    string,null
    Restrictions
    Description

    The HS/HTS code for the item. Either HS or HTS codes can be supplied, but HTS is recommended.

    N.B. Formatting such as spaces and periods are ignored, and may be removed.

{
  "description": "chocolate cake",
  "quantity": 1,
  "value": 0,
  "currency_code": "USD",
  "mass": 5000,
  "product_identifier": "SB-D80-DCCF",
  "hs_tariff_code": "1901200000"
}

Customs Identifier Model

Properties

  • Name
    entity_type
    Type
    string
    Restrictions
    Description

    The entity type corresponding to the identifier.

    One of:

    - import
    - export
    - all

    For example:

    In the US, a PFC/EEL is needed for exporting goods internationally. So the entity_type would be export.

    Possible Enum Values

    import
    export
    all
  • Name
    identifier_type
    Type
    string
    Restrictions
    Description

    The type of customs identifier. Currently supported values are:

    - eei: Electronic Export Information, mainly used when exporting from the US, this is either an EEL code, or a PFC (ITN) reference number.
    - mrn: Movement Reference Number, generally used for European customs handling, both for import and export.
    - license: If items within the shipment require a license, the identifier of the license.
    - certificate: If items within the shipment require a certificate, the identifier of the certificate.
    - other: If the customs identifier does not fit one of the above, use this type. Currently identifiers with type other are only stored for reference, and are not passed to the carrier, though this may change without prior notice.

    Possible Enum Values

    license
    certificate
    eei
    mrn
    other
  • Name
    value
    Type
    string
    Restrictions
    Description

    The value of the identifier itself.

  • Name
    issuing_country_code
    Type
    string,null
    Restrictions
    Description

    If known, the country code of the authority that issued the customs identifier.

    For example, an EEL/PFC identifier would have the US set as the country code.

{
  "entity_type": "import",
  "identifier_type": "license",
  "value": "string",
  "issuing_country_code": "string"
}
GET/shipments

Get Shipments

Retrieves a list of shipments associated with the account.

Query Parameters

  • Name
    include_fields
    Type
    array[string]
    Restrictions
    Description

    The fields that should be included in the response. This should be a comma-separated list of values with the following possible options: origin_address, destination_address, return_address, rates, selected_rate, documents, errors

  • Name
    batch_id
    Type
    string
    Restrictions
    Description

    A batch id to filter shipments by.

  • Name
    cursor
    Type
    string
    Restrictions
    Description

    A pagination pointer supplied in a previous request.

  • Name
    limit
    Type
    string
    Restrictions
    Description

    The maximum number of results returned in the set.

Enumerated Values

ParameterValue
include_fieldsorigin_address
include_fieldsdestination_address
include_fieldsreturn_address
include_fieldsrates
include_fieldsselected_rate
include_fieldsdocuments
include_fieldserrors

Request

GET
/shipments
curl --request GET \
--url https://api.envoy.one/shipments \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "data": [
    {
      "id": "shp_0ujzPyRiIAffKhBux4PvQdDqMHY",
      "addresses": {
        "destination": {
          "address": "[Object]",
          "contact": "[Object]",
          "display_name": "Work",
          "metadata": "[Object]",
          "marketplaces": "[Object]",
          "coordinates": "[Object]"
        },
        "origin": {
          "address": "[Object]",
          "contact": "[Object]",
          "display_name": "Work",
          "metadata": "[Object]",
          "marketplaces": "[Object]",
          "coordinates": "[Object]"
        },
        "return": {
          "address": "[Object]",
          "contact": "[Object]",
          "display_name": "Work",
          "metadata": "[Object]",
          "marketplaces": "[Object]",
          "coordinates": "[Object]"
        },
        "location_configuration_id": "lc_2iFuzwcptRh9xt93ICDzK0vOszc"
      },
      "tax_identifiers": [
        {
          "taxable_entity_type": "sender",
          "identifier_type": "ioss",
          "value": "IM0123456789",
          "issuing_country_code": "string"
        }
      ],
      "packages": [
        {
          "name": "string",
          "geometry": {
            "length": null,
            "width": null,
            "height": null,
            "mass": null
          },
          "predefined_package_code": "string"
        }
      ],
      "customs": {
        "contents_type": "merchandise",
        "contents_description": "automobile parts",
        "declarant": {
          "name": "string",
          "certify": true,
          "date": null
        },
        "incoterm": "DDP",
        "restriction_type": "other",
        "restriction_description": "string",
        "declaration_message": "string",
        "items": null,
        "identifiers": [
          {
            "entity_type": null,
            "identifier_type": null,
            "value": null,
            "issuing_country_code": null
          }
        ]
      },
      "options": {
        "shipping": {
          "access_code": "473281",
          "commercial_address": false,
          "currency_code": "USD",
          "date": "2022-07-11T00:00:00.00Z",
          "delivery_confirmation": false,
          "dry_ice_mass": 2500,
          "dropoff_type": "regular_pickup",
          "handling_instructions": "Leave behind plant pot in front porch.",
          "high_security": null,
          "hold_for_pickup": false,
          "invalid_address_handling": "forward_or_return",
          "is_return": false,
          "leave_safe": null,
          "machinable": null,
          "non_delivery": "return",
          "restricted_substances": null,
          "safe_place": "Garden Shed",
          "saturday_delivery": false,
          "signature_required": null,
          "signature_type": "standard",
          "tracked_service": null
        },
        "label": {
          "format": "pdf",
          "size": "4x6",
          "custom_data": null
        },
        "insurance": {
          "value": 55000,
          "currency_code": "USD"
        }
      },
      "carrier": {
        "carrier_code": "string",
        "service_code": "string",
        "carrier_accounts": [
          "string"
        ]
      },
      "name": "ORDER-273548",
      "documents": [
        {
          "id": "doc_2iBgUNtezju7lmzmfOoJO8cnsVS",
          "type": "label",
          "file_name": "2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png",
          "file_type": "image/png",
          "file_size": 129842,
          "file_url": "https://envoy-shipment-files.s3.amazonaws.com/labels/2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png?AWSAccessKeyId=AKIAY27LA84LC8DHB20X&Signature=kZY1RHl%2BBIClJ0UpjpKtAeqZqJA%3D&Expires=1725464510",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z"
        }
      ],
      "rates": [
        {
          "id": "string",
          "carrier": {
            "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
            "name": "UPS",
            "handle": "ups"
          },
          "carrier_service": {
            "id": "cs_2iBgUNbKrgj7uVrsSiiF5ZhTelp",
            "name": "Express",
            "handle": "express"
          },
          "carrier_account": null,
          "rate": 1650,
          "currency_code": "USD",
          "delivery_days": 3,
          "ship_date": "2024-06-18T14:15:22Z",
          "delivery_date": "2024-06-21T14:15:22Z",
          "guaranteed_delivery_date": "2024-06-22T14:15:22Z"
        }
      ],
      "service": {
        "rate": "rate_2iBgUKWHmQlBjYQyx9fAGMvcCEp",
        "carrier": {
          "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
          "name": "UPS",
          "handle": "ups"
        },
        "carrier_service": {
          "id": "cs_2iBgUOHPuWh0Hvjc81euqKXTW5N",
          "name": "Express",
          "handle": "express"
        },
        "carrier_account": {
          "id": "ca_2iBgUOHPuWh0Hvjc81euqKXTW5N",
          "name": "Main Account",
          "handle": null
        }
      },
      "status": "purchased",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "errors": [
        {
          "type": "rate_error",
          "code": "rates_unavailable",
          "source": "provider",
          "message": "rates are not available for the provided shipment"
        }
      ]
    }
  ],
  "next_cursor": "WyIyMDIzLTAzLTIxVDAwOjM1OjU5LjczMDYyMVoiXQ==",
  "previous_cursor": "WyIyMDIzLTAzLTE5VDA0OjI4OjAxLjQ4NDg5WiJd",
  "limit": 20
}

undefined

POST/shipments

Create Shipment

Creates a shipment.

Due to the variability in upstream services of couriers in terms of reliability, latency and response, when a shipment is created we start the creation as a long-running task. If the upstream provider returns the created shipment within a few seconds, we return the created shipment to the client, represented with the 201 Created status code.

For shipments that take longer to create, after a few seconds the client will receive a 202 Accepted status response, with the body containing information about the created shipment that can be used to poll the status of the shipment. If the shipment is not immediately required, we recommend using webhook events to be updated on the status of the shipment, though you will likely need to store the id returned in the response to correlate requests.

Request

POST
/shipments
curl --request POST \
--url https://api.envoy.one/shipments \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"name":"ORDER-273548","addresses":{"destination":{"contact":{"name":"Jenny Falkner","email_address":"[email protected]","phone_number":"+447261812509"},"address":{"line_1":"179 N Harbor Dr","city":"Redondo Beach","province":"CA","post_code":"90277","country_code":"US"}},"origin":{"contact":{"company":"Axis Distribution","email_address":"[email protected]","phone_number":"+442046194615"},"address":{"line_1":"417 Montgomery Street","line_2":"5th Floor","city":"San Francisco","province":"CA","post_code":"94104","country_code":"US"}},"return":{"contact":{"company":"Axis Distribution","email_address":"[email protected]","phone_number":"+442046194615"},"address":{"line_1":"417 Montgomery Street","line_2":"5th Floor","city":"San Francisco","province":"CA","post_code":"94104","country_code":"US"}}},"packages":[{"geometry":{"length":600,"width":400,"height":250,"mass":4500}}],"tax_identifiers":[{"taxable_entity_type":"sender","identifier_type":"vat","value":"478321451","issuing_country_code":"GB"}],"options":{"shipping":{"handling_instructions":"Leave outside front door."}}}'

Response

{
  "id": "shp_0ujzPyRiIAffKhBux4PvQdDqMHY",
  "addresses": {
    "destination": {
      "address": {
        "line_1": "29 Holgate Rd",
        "line_2": "Segwick Street",
        "line_3": "Kelvedon",
        "city": "RACKWICK",
        "province": "Cambershire",
        "post_code": "KW16 2PE",
        "country_code": "GB"
      },
      "contact": {
        "name": "Francesca Brady",
        "company": "Malvinex Corp"
      },
      "display_name": "Work",
      "metadata": {
        "contact_email": "[email protected]"
      },
      "marketplaces": {
        "shopify": "657847832011"
      },
      "coordinates": {
        "latitude": 51.5134297,
        "longitude": -0.103145,
        "confidence": 1
      }
    },
    "origin": {
      "address": {
        "line_1": "29 Holgate Rd",
        "line_2": "Segwick Street",
        "line_3": "Kelvedon",
        "city": "RACKWICK",
        "province": "Cambershire",
        "post_code": "KW16 2PE",
        "country_code": "GB"
      },
      "contact": {
        "name": "Francesca Brady",
        "company": "Malvinex Corp"
      },
      "display_name": "Work",
      "metadata": {
        "contact_email": "[email protected]"
      },
      "marketplaces": {
        "shopify": "657847832011"
      },
      "coordinates": {
        "latitude": 51.5134297,
        "longitude": -0.103145,
        "confidence": 1
      }
    },
    "return": {
      "address": {
        "line_1": "29 Holgate Rd",
        "line_2": "Segwick Street",
        "line_3": "Kelvedon",
        "city": "RACKWICK",
        "province": "Cambershire",
        "post_code": "KW16 2PE",
        "country_code": "GB"
      },
      "contact": {
        "name": "Francesca Brady",
        "company": "Malvinex Corp"
      },
      "display_name": "Work",
      "metadata": {
        "contact_email": "[email protected]"
      },
      "marketplaces": {
        "shopify": "657847832011"
      },
      "coordinates": {
        "latitude": 51.5134297,
        "longitude": -0.103145,
        "confidence": 1
      }
    },
    "location_configuration_id": "lc_2iFuzwcptRh9xt93ICDzK0vOszc"
  },
  "tax_identifiers": [
    {
      "taxable_entity_type": "sender",
      "identifier_type": "ioss",
      "value": "IM0123456789",
      "issuing_country_code": "string"
    }
  ],
  "packages": [
    {
      "name": "string",
      "geometry": {
        "length": 0,
        "width": 0,
        "height": 0,
        "mass": 0
      },
      "predefined_package_code": "string"
    }
  ],
  "customs": {
    "contents_type": "merchandise",
    "contents_description": "automobile parts",
    "declarant": {
      "name": "string",
      "certify": true,
      "date": "string"
    },
    "incoterm": "DDP",
    "restriction_type": "other",
    "restriction_description": "string",
    "declaration_message": "string",
    "items": null,
    "identifiers": [
      {
        "entity_type": "import",
        "identifier_type": "license",
        "value": "string",
        "issuing_country_code": "string"
      }
    ]
  },
  "options": {
    "shipping": {
      "access_code": "473281",
      "commercial_address": false,
      "currency_code": "USD",
      "date": "2022-07-11T00:00:00.00Z",
      "delivery_confirmation": false,
      "dry_ice_mass": 2500,
      "dropoff_type": "regular_pickup",
      "handling_instructions": "Leave behind plant pot in front porch.",
      "high_security": true,
      "hold_for_pickup": false,
      "invalid_address_handling": "forward_or_return",
      "is_return": false,
      "leave_safe": true,
      "machinable": true,
      "non_delivery": "return",
      "restricted_substances": [
        "alcohol"
      ],
      "safe_place": "Garden Shed",
      "saturday_delivery": false,
      "signature_required": true,
      "signature_type": "standard",
      "tracked_service": true
    },
    "label": {
      "format": "pdf",
      "size": "4x6",
      "custom_data": {
        "text_lines": {
          "line_1": null,
          "line_2": null,
          "line_3": null
        },
        "line_codes": {
          "line_1": null,
          "line_2": null,
          "line_3": null
        },
        "barcodes": {
          "barcode_1": null,
          "barcode_2": null,
          "barcode_3": null
        }
      }
    },
    "insurance": {
      "value": 55000,
      "currency_code": "USD"
    }
  },
  "carrier": {
    "carrier_code": "string",
    "service_code": "string",
    "carrier_accounts": [
      "string"
    ]
  },
  "name": "ORDER-273548",
  "documents": [
    {
      "id": "doc_2iBgUNtezju7lmzmfOoJO8cnsVS",
      "type": "label",
      "file_name": "2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png",
      "file_type": "image/png",
      "file_size": 129842,
      "file_url": "https://envoy-shipment-files.s3.amazonaws.com/labels/2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png?AWSAccessKeyId=AKIAY27LA84LC8DHB20X&Signature=kZY1RHl%2BBIClJ0UpjpKtAeqZqJA%3D&Expires=1725464510",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "rates": [
    {
      "id": "string",
      "carrier": {
        "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
        "name": "UPS",
        "handle": "ups"
      },
      "carrier_service": {
        "id": "cs_2iBgUNbKrgj7uVrsSiiF5ZhTelp",
        "name": "Express",
        "handle": "express"
      },
      "carrier_account": null,
      "rate": 1650,
      "currency_code": "USD",
      "delivery_days": 3,
      "ship_date": "2024-06-18T14:15:22Z",
      "delivery_date": "2024-06-21T14:15:22Z",
      "guaranteed_delivery_date": "2024-06-22T14:15:22Z"
    }
  ],
  "service": {
    "rate": "rate_2iBgUKWHmQlBjYQyx9fAGMvcCEp",
    "carrier": {
      "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "UPS",
      "handle": "ups"
    },
    "carrier_service": {
      "id": "cs_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "Express",
      "handle": "express"
    },
    "carrier_account": {
      "id": "ca_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "Main Account",
      "handle": null
    }
  },
  "status": "purchased",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "errors": [
    {
      "type": "rate_error",
      "code": "rates_unavailable",
      "source": "provider",
      "message": "rates are not available for the provided shipment"
    }
  ]
}

undefined

GET/shipments/{id}

Get Individual Shipment

Retrieves an individual shipment.

Path Parameters

  • Name
    id
    Type
    string
    Restrictions
    Description

    The unique ID for the shipment.

Request

GET
/shipments/{id}
curl --request GET \
--url https://api.envoy.one/shipments/shp_2iEunQY2MPyegzQuwvfc8wcsPgk \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "id": "shp_0ujzPyRiIAffKhBux4PvQdDqMHY",
  "addresses": {
    "destination": {
      "address": {
        "line_1": "29 Holgate Rd",
        "line_2": "Segwick Street",
        "line_3": "Kelvedon",
        "city": "RACKWICK",
        "province": "Cambershire",
        "post_code": "KW16 2PE",
        "country_code": "GB"
      },
      "contact": {
        "name": "Francesca Brady",
        "company": "Malvinex Corp"
      },
      "display_name": "Work",
      "metadata": {
        "contact_email": "[email protected]"
      },
      "marketplaces": {
        "shopify": "657847832011"
      },
      "coordinates": {
        "latitude": 51.5134297,
        "longitude": -0.103145,
        "confidence": 1
      }
    },
    "origin": {
      "address": {
        "line_1": "29 Holgate Rd",
        "line_2": "Segwick Street",
        "line_3": "Kelvedon",
        "city": "RACKWICK",
        "province": "Cambershire",
        "post_code": "KW16 2PE",
        "country_code": "GB"
      },
      "contact": {
        "name": "Francesca Brady",
        "company": "Malvinex Corp"
      },
      "display_name": "Work",
      "metadata": {
        "contact_email": "[email protected]"
      },
      "marketplaces": {
        "shopify": "657847832011"
      },
      "coordinates": {
        "latitude": 51.5134297,
        "longitude": -0.103145,
        "confidence": 1
      }
    },
    "return": {
      "address": {
        "line_1": "29 Holgate Rd",
        "line_2": "Segwick Street",
        "line_3": "Kelvedon",
        "city": "RACKWICK",
        "province": "Cambershire",
        "post_code": "KW16 2PE",
        "country_code": "GB"
      },
      "contact": {
        "name": "Francesca Brady",
        "company": "Malvinex Corp"
      },
      "display_name": "Work",
      "metadata": {
        "contact_email": "[email protected]"
      },
      "marketplaces": {
        "shopify": "657847832011"
      },
      "coordinates": {
        "latitude": 51.5134297,
        "longitude": -0.103145,
        "confidence": 1
      }
    },
    "location_configuration_id": "lc_2iFuzwcptRh9xt93ICDzK0vOszc"
  },
  "tax_identifiers": [
    {
      "taxable_entity_type": "sender",
      "identifier_type": "ioss",
      "value": "IM0123456789",
      "issuing_country_code": "string"
    }
  ],
  "packages": [
    {
      "name": "string",
      "geometry": {
        "length": 0,
        "width": 0,
        "height": 0,
        "mass": 0
      },
      "predefined_package_code": "string"
    }
  ],
  "customs": {
    "contents_type": "merchandise",
    "contents_description": "automobile parts",
    "declarant": {
      "name": "string",
      "certify": true,
      "date": "string"
    },
    "incoterm": "DDP",
    "restriction_type": "other",
    "restriction_description": "string",
    "declaration_message": "string",
    "items": null,
    "identifiers": [
      {
        "entity_type": "import",
        "identifier_type": "license",
        "value": "string",
        "issuing_country_code": "string"
      }
    ]
  },
  "options": {
    "shipping": {
      "access_code": "473281",
      "commercial_address": false,
      "currency_code": "USD",
      "date": "2022-07-11T00:00:00.00Z",
      "delivery_confirmation": false,
      "dry_ice_mass": 2500,
      "dropoff_type": "regular_pickup",
      "handling_instructions": "Leave behind plant pot in front porch.",
      "high_security": true,
      "hold_for_pickup": false,
      "invalid_address_handling": "forward_or_return",
      "is_return": false,
      "leave_safe": true,
      "machinable": true,
      "non_delivery": "return",
      "restricted_substances": [
        "alcohol"
      ],
      "safe_place": "Garden Shed",
      "saturday_delivery": false,
      "signature_required": true,
      "signature_type": "standard",
      "tracked_service": true
    },
    "label": {
      "format": "pdf",
      "size": "4x6",
      "custom_data": {
        "text_lines": {
          "line_1": null,
          "line_2": null,
          "line_3": null
        },
        "line_codes": {
          "line_1": null,
          "line_2": null,
          "line_3": null
        },
        "barcodes": {
          "barcode_1": null,
          "barcode_2": null,
          "barcode_3": null
        }
      }
    },
    "insurance": {
      "value": 55000,
      "currency_code": "USD"
    }
  },
  "carrier": {
    "carrier_code": "string",
    "service_code": "string",
    "carrier_accounts": [
      "string"
    ]
  },
  "name": "ORDER-273548",
  "documents": [
    {
      "id": "doc_2iBgUNtezju7lmzmfOoJO8cnsVS",
      "type": "label",
      "file_name": "2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png",
      "file_type": "image/png",
      "file_size": 129842,
      "file_url": "https://envoy-shipment-files.s3.amazonaws.com/labels/2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png?AWSAccessKeyId=AKIAY27LA84LC8DHB20X&Signature=kZY1RHl%2BBIClJ0UpjpKtAeqZqJA%3D&Expires=1725464510",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "rates": [
    {
      "id": "string",
      "carrier": {
        "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
        "name": "UPS",
        "handle": "ups"
      },
      "carrier_service": {
        "id": "cs_2iBgUNbKrgj7uVrsSiiF5ZhTelp",
        "name": "Express",
        "handle": "express"
      },
      "carrier_account": null,
      "rate": 1650,
      "currency_code": "USD",
      "delivery_days": 3,
      "ship_date": "2024-06-18T14:15:22Z",
      "delivery_date": "2024-06-21T14:15:22Z",
      "guaranteed_delivery_date": "2024-06-22T14:15:22Z"
    }
  ],
  "service": {
    "rate": "rate_2iBgUKWHmQlBjYQyx9fAGMvcCEp",
    "carrier": {
      "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "UPS",
      "handle": "ups"
    },
    "carrier_service": {
      "id": "cs_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "Express",
      "handle": "express"
    },
    "carrier_account": {
      "id": "ca_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "Main Account",
      "handle": null
    }
  },
  "status": "purchased",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "errors": [
    {
      "type": "rate_error",
      "code": "rates_unavailable",
      "source": "provider",
      "message": "rates are not available for the provided shipment"
    }
  ]
}

undefined

POST/shipments/{id}/purchase

Buy Shipment

Finalises (purchases) a shipment that was previously created & rated.

Path Parameters

  • Name
    id
    Type
    string
    Restrictions
    Description

    The unique ID for the shipment.

Request

POST
/shipments/{id}/purchase
curl --request POST \
--url https://api.envoy.one/shipments/shp_2iEunQY2MPyegzQuwvfc8wcsPgk/purchase \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"rate":"string"}'

Response

{
  "id": "shp_0ujzPyRiIAffKhBux4PvQdDqMHY",
  "addresses": {
    "destination": {
      "address": {
        "line_1": "29 Holgate Rd",
        "line_2": "Segwick Street",
        "line_3": "Kelvedon",
        "city": "RACKWICK",
        "province": "Cambershire",
        "post_code": "KW16 2PE",
        "country_code": "GB"
      },
      "contact": {
        "name": "Francesca Brady",
        "company": "Malvinex Corp"
      },
      "display_name": "Work",
      "metadata": {
        "contact_email": "[email protected]"
      },
      "marketplaces": {
        "shopify": "657847832011"
      },
      "coordinates": {
        "latitude": 51.5134297,
        "longitude": -0.103145,
        "confidence": 1
      }
    },
    "origin": {
      "address": {
        "line_1": "29 Holgate Rd",
        "line_2": "Segwick Street",
        "line_3": "Kelvedon",
        "city": "RACKWICK",
        "province": "Cambershire",
        "post_code": "KW16 2PE",
        "country_code": "GB"
      },
      "contact": {
        "name": "Francesca Brady",
        "company": "Malvinex Corp"
      },
      "display_name": "Work",
      "metadata": {
        "contact_email": "[email protected]"
      },
      "marketplaces": {
        "shopify": "657847832011"
      },
      "coordinates": {
        "latitude": 51.5134297,
        "longitude": -0.103145,
        "confidence": 1
      }
    },
    "return": {
      "address": {
        "line_1": "29 Holgate Rd",
        "line_2": "Segwick Street",
        "line_3": "Kelvedon",
        "city": "RACKWICK",
        "province": "Cambershire",
        "post_code": "KW16 2PE",
        "country_code": "GB"
      },
      "contact": {
        "name": "Francesca Brady",
        "company": "Malvinex Corp"
      },
      "display_name": "Work",
      "metadata": {
        "contact_email": "[email protected]"
      },
      "marketplaces": {
        "shopify": "657847832011"
      },
      "coordinates": {
        "latitude": 51.5134297,
        "longitude": -0.103145,
        "confidence": 1
      }
    },
    "location_configuration_id": "lc_2iFuzwcptRh9xt93ICDzK0vOszc"
  },
  "tax_identifiers": [
    {
      "taxable_entity_type": "sender",
      "identifier_type": "ioss",
      "value": "IM0123456789",
      "issuing_country_code": "string"
    }
  ],
  "packages": [
    {
      "name": "string",
      "geometry": {
        "length": 0,
        "width": 0,
        "height": 0,
        "mass": 0
      },
      "predefined_package_code": "string"
    }
  ],
  "customs": {
    "contents_type": "merchandise",
    "contents_description": "automobile parts",
    "declarant": {
      "name": "string",
      "certify": true,
      "date": "string"
    },
    "incoterm": "DDP",
    "restriction_type": "other",
    "restriction_description": "string",
    "declaration_message": "string",
    "items": null,
    "identifiers": [
      {
        "entity_type": "import",
        "identifier_type": "license",
        "value": "string",
        "issuing_country_code": "string"
      }
    ]
  },
  "options": {
    "shipping": {
      "access_code": "473281",
      "commercial_address": false,
      "currency_code": "USD",
      "date": "2022-07-11T00:00:00.00Z",
      "delivery_confirmation": false,
      "dry_ice_mass": 2500,
      "dropoff_type": "regular_pickup",
      "handling_instructions": "Leave behind plant pot in front porch.",
      "high_security": true,
      "hold_for_pickup": false,
      "invalid_address_handling": "forward_or_return",
      "is_return": false,
      "leave_safe": true,
      "machinable": true,
      "non_delivery": "return",
      "restricted_substances": [
        "alcohol"
      ],
      "safe_place": "Garden Shed",
      "saturday_delivery": false,
      "signature_required": true,
      "signature_type": "standard",
      "tracked_service": true
    },
    "label": {
      "format": "pdf",
      "size": "4x6",
      "custom_data": {
        "text_lines": {
          "line_1": null,
          "line_2": null,
          "line_3": null
        },
        "line_codes": {
          "line_1": null,
          "line_2": null,
          "line_3": null
        },
        "barcodes": {
          "barcode_1": null,
          "barcode_2": null,
          "barcode_3": null
        }
      }
    },
    "insurance": {
      "value": 55000,
      "currency_code": "USD"
    }
  },
  "carrier": {
    "carrier_code": "string",
    "service_code": "string",
    "carrier_accounts": [
      "string"
    ]
  },
  "name": "ORDER-273548",
  "documents": [
    {
      "id": "doc_2iBgUNtezju7lmzmfOoJO8cnsVS",
      "type": "label",
      "file_name": "2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png",
      "file_type": "image/png",
      "file_size": 129842,
      "file_url": "https://envoy-shipment-files.s3.amazonaws.com/labels/2iBgUMZPAyHoQlX2RnuaobI5yKk_label_0.png?AWSAccessKeyId=AKIAY27LA84LC8DHB20X&Signature=kZY1RHl%2BBIClJ0UpjpKtAeqZqJA%3D&Expires=1725464510",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "rates": [
    {
      "id": "string",
      "carrier": {
        "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
        "name": "UPS",
        "handle": "ups"
      },
      "carrier_service": {
        "id": "cs_2iBgUNbKrgj7uVrsSiiF5ZhTelp",
        "name": "Express",
        "handle": "express"
      },
      "carrier_account": null,
      "rate": 1650,
      "currency_code": "USD",
      "delivery_days": 3,
      "ship_date": "2024-06-18T14:15:22Z",
      "delivery_date": "2024-06-21T14:15:22Z",
      "guaranteed_delivery_date": "2024-06-22T14:15:22Z"
    }
  ],
  "service": {
    "rate": "rate_2iBgUKWHmQlBjYQyx9fAGMvcCEp",
    "carrier": {
      "id": "car_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "UPS",
      "handle": "ups"
    },
    "carrier_service": {
      "id": "cs_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "Express",
      "handle": "express"
    },
    "carrier_account": {
      "id": "ca_2iBgUOHPuWh0Hvjc81euqKXTW5N",
      "name": "Main Account",
      "handle": null
    }
  },
  "status": "purchased",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "errors": [
    {
      "type": "rate_error",
      "code": "rates_unavailable",
      "source": "provider",
      "message": "rates are not available for the provided shipment"
    }
  ]
}

undefined